Latest revision as of 04:44, 9 January 2014

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.

GBrowse Installation

This section describes the various ways to get GBrowse up and running.

GBrowse Virtual Machines

The easiest way to get started using GBrowse2 is to use one of the pre-packaged virtual machines with all libraries, tools and other dependencies preinstalled. There are two standard GBrowse VMs, one for running on your desktop using VirtualBox, and the other for running on Amazon Web Services.

Please see GBrowse2 VMs for a list of the VMs that are available to use, plus a quick start guide to using these virtual machines.

Ubuntu 11.10 and higher Binary Installs

In Ubuntu versions 11.10 and higher, you can install GBrowse2 and all its dependencies from the Software Center or from the command line. From the Software Center, search for "gbrowse" and click the "install" button. You may also wish to install the "gbrowse_data" package, which includes example data files and tutorials.

From the command line, run the following:

> apt-get install gbrowse gbrowse_data

Debian "sid" Binary Installs

In Debian and Debian-related systems, run the following command:

>aptitude install gbrowse gbrowse_data

You might also wish to browse the GBrowse Debian package pages.

The current version in the Debian package is 2.39, which is a bit old but quite stable. The package will be updated at some point in the not-so-distant future.

Debian "wheezy" Binary Installs

In Debian and Debian-related systems, run the following command:

>aptitude install gbrowse gbrowse-data gbrowse-calign

You might also wish to browse the GBrowse Debian package pages.

Installation on Older Ubuntu and Debian Systems

First install prerequisites following the instructions at GBrowse_2.0_Prerequisites#DEB Systems (apt). Then perform the last steps manually as described in GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell.

Installation on RedHat, CentOS and other RPM Systems

First install prerequisites following the instructions at GBrowse_2.0_Prerequisites#RPM Systems (yum). Then perform the last steps using the CPAN shell as described in GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell.

Installation on MacOSX Systems

Install the prerequisites following the instructions at GBrowse_2.0_Prerequisites#MacOSX. Then perform the last steps using the CPAN shell as described in GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell and GBrowse_2.0_Install_HOWTO#Configure_in_Mac_OS_X_10.6.6.

Installation from Source Code

Installation from source code is described in GBrowse_2.0_Install_HOWTO#Installing_Manually.

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.

For GBrowse 1.X configuration, see: GBrowse Configuration HOWTO.

Configuring GBrowse

GBrowse is controlled by a set of text configuration files. You will log into the web server machine and edit these files using a text editor. Alternatively you can use WebGBrowse, which is a web-based system for initializing, configuring and customizing GBrowse databases. It is an add-on to GBrowse and should only be installed after GBrowse is up and running.

This section discusses manual editing of GBrowse's configuration files.

GBrowse's options are controlled by a master config file, GBrowse.conf which contains site-specific options that apply to all data sources, and one or more Data source-specific configuration files that 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
#truetype      = 1    # use truetype fonts for rendering tracks; disabled by default.

# 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

instructions section   = open
upload_tracks section  = closed
search section         = open
overview section       = open
region section         = open
detail section         = open
tracks section         = open
display_settings section = closed

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

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.

max_render_processes

GBrowse launches a subprocess for each track it renders. This option will limit the number of simultaneous subprocesses that can be launched in order to avoid overloading the system. The default is four; you may wish to adjust this upward on a system with 4 or more CPUs. A good choice is between one and two times the number of CPUs/cores on the server system:

max_render_processes = 8

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.

The autocomplete setting also applies to the "Custom Tracks" and "Community Tracks" sections, and allows users to search the user account database for public tracks via autocomplete. See GBrowse_Configuration/Authentication for more information on the user account database.

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)

truecolor: If set to a true value, then the tracks will be rendered as full-color 24-bit images, improving appearance at the cost of larger images. The effect may be noticeable on a slow internet connection.

truetype: If set to a true value, then the fonts in track images will be rendered using truetype fonts installed on the server. A value of "1" selects a safe default font. A string value can be used to select a particular font, such as "Droid Sans" or "Helvetica-9". This option only works on versions of GBrowse from 2.55 onward, and only if Bio::Graphics 2.33 or higher is installed.

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 Bio::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 Bio::Graphics color value, such as "red:0.8".

hilite height: This option controls the height of the draggable region marker, which highlights the currently selected region

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

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 Bio::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.

instructions section, upload_tracks section, search section, overview section, region section, detail section, tracks section, display_settings section: These options control whether a section is toggled open initially ("open"), or toggled closed ("closed"). In addition, for the "overview section", "region section" and "detail section", you can specify a value of "hide" in which case the section isn't shown at all. Generally this only makes sense for the region section.

category default state: As described in the track configuration section, a track can be placed in a category or subcategory. The categories can be toggled open and closed. The "category state" option, described next, allows you to configure the toggle state of each category and subcategory when the user first accesses the page. If a category is not explicitly named, then this option is consulted to find the default. Values are either "open" to make each category open by default, or "closed". For convenience, you may use the integer value 0 for "closed" or 1 for "open".

category state

This option controls whether a category or subcategory is open or closed when the user first visits the page, or resets his state with the "Reset" menu choice. The format is as shown in this example:

category state = Genes           open
                 Genes:Coding    open
                 Genes:Noncoding closed

Categories are identified by their names; subcategories and sub-subcategories are indicated by dividing the subcategories by ":" characters. You may use "open" to indicate that a category is open at first, or "closed" to collapse it on the first page load. "1" and "0" can be used instead of "open" and "closed".

Fast Track Panning (new in version 2.20)

This configures fast track panning, the ability for a user to drag/pan the details tracks back and forth to instantly see more of the image. Extra wide images are preloaded from the server to accomplish this, so it may affect the initial image load time.

details multiplier: How much extra image data to load. A value of 3.0 means that three times the viewable image width will be loaded. The default is 1.0, which means that fast track panning is turned off and GBrowse behaves as usual.

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.

Upload Database Settings

These options configure the backend database that is used to store the information that a user uploads when he or she creates custom tracks. The default is to choose a workable database system based on the Perl DBI drivers installed on the system. See Configuring the Uploaded Track Database for detailed configuration information.

upload_db_adaptor: Which database backend to use for custom tracks. Valid options are "DBI::SQLite", "DBI::mysql", "berkeleydb" and "memory". The SQLite database backend combines great performance with little or no maintenance, but does require the perl DBI::SQLite module to be installed. The memory backend requires no additional Perl modules, but is only appropriate for very small uploads (less than 10,000 features). The DBI::mysql backend has the best performance, but needs additional configuration in order to make it possible for GBrowse to create and drop databases dynamically.

upload_db_host: When using the DBI::mysql backend, this specifies the host on which the mysql DBMS is running. (Default "localhost").

upload_db_user: When using the DBI::mysql backend, this specifies the user that has access to the mysql server. This user must have database create/drop privileges for databases beginning with the string "userdata_". (Default "gbrowse").

upload_db_pass: When using the DBI::mysql backend, this specifies the password for the user named by upload_db_user. (Default no password).

admin_account: The name of the administrator account that has privileges to upload and configure public tracks. See The Admin Interface for more details.

admin_dbs: The path used to store data files uploaded by the administrator named in admin_account. See The Admin Interface for more details.

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.

Configuring Genomic Regions

Several options allow you to configure the behaviour 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.

option	default value	description
region segment	50000 (?)	NOT DESCRIBED HERE PREVIOUSLY! DOES IT APPLY TO 2.0?? DESCRIBED ELSEWHERE (If this configuration option is set, a new "region panel" will appear that is intermediate in size between the overview and the detail panel. The value of this option becomes the size of the region panel in base pairs.)
max segment	5000000 (?)	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	100 500 1000 5000 50000 100000 (?)	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.
fine zoom	10%	This option controls the increment that the user will zoom in or out when pressing the "+" and "-" buttons in the navigation bar.
default segment	5000 (?)	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	1000 5000 10000 20000 (?)	This option is similar to zoom levels except that the list of zoom levels applies to the region panel.
default region	5000 (?)	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

These can be used with callbacks to bring in local or external html files, e.g.

header = sub{
       open FILEHANDLE, 'somefile.txt' or die $!;
       my $html_header = do { local $/; <FILEHANDLE> };
       return $html_header;
       }

or

header = sub{
       use LWP::Simple;
       my $html_header = get("http://example.org/header.html");
       return $html_header;
       }

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 a 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

metadata

You can use this option to create machine- and human-readable information about your database. It is used to populate the information that appears when the user selects the "About this database" menu item. The full format is as follows:

 metadata =
       -description             Example GBrowse database containing information from WormBase and modENCODE.
       -maintainer              Lincoln Stein <lincoln.stein@gmail.com>
       -created                 2010-1-4
       -modified                2009-9-1
       -authority               WS
       -coordinates             http://www.dasregistry.org/coordsys/CS_DS109
       -coordinates_version     170
       -source                  Chromosome
       -testrange               I:7385068..7387651
       -species                 Caenorhabditis elegans
       -taxid                   6239

All the fields are optional. -description provides a human-readable description of the database. -maintainer provides a name and contact address for users. -created and -modified give the date (in year-month-day format) when the database was created and modified. -species and -taxid provide the systematic species name and NCBI taxon ID for the species.

-authority, -coordinates, and -coordinates_version together provide information on the genome build used for this database. -authority is a prefix to be added to the coordinates_version that indicates the organization that performed the build. You can make one up, but it is better to consult a growing registry of these prefixes at http://www.dasregistry.org/help_coordsys.jsp; you can easily add a new one using the registry service. Registered coordinate systems receive a URL from the registry, which you can use for the -coordinates option.

-source indicates the type of the coordinate system you are using, usually either "Chromosome" or "Contig."

-testrange provides an example coordinate range that users can try out.

Should you wish to continue a long description across multiple lines, simply leave whitespace in front of the second and subsequent lines.

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.

seqid_prefix

It sometimes happens that different web databases disagree about how chromosomes are named. For example, in C. elegans, WormBase data dumps use chromosomes named "I", "II", etc, while the UCSC Genome Browser uses "chrI", "chrII", etc. This makes interoperation difficult via Galaxy and other workflow managers. If seqid_prefix is defined, then the prefix will be added to the chromosome names for all data dumps from the browser and stripped from all data uploads. For example, WormBase can specify:

 seqid_prefix = chr

to add "chr" to all its chromosome names on the way to Galaxy/UCSC and to strip "chr" from all chromosome names received from Galaxy/UCSC.

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 = exact, -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!
heuristic: 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

To add tracks to a data source, you will create a series of one or more track definition stanzas. Alternatively, if you have the user account login system running, you can use the admin interface to upload, configure and manage tracks remotely. This section describes the direct method of configuring tracks by directly editing the data source configuration file.

Following the database stanzas in the data source configuration file 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 Backend 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 type and a 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 "type" 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.

inline_imagemaps: This option is new in version 2.44. In previous versions, the imagemap data, which tells the browser what to do when the user hovers over a feature or clicks on it, was generated at the time the track is generated. However, this slows down track generation when there are many features, such as when showing next generation sequencing data. In version 2.44, the imagemaps are only generated as needed when the use clicks or hovers over a feature. The downside of this is that popup balloons are slightly delayed when GBrowse is running as a vanilla CGI application (there is no noticeable delay under FastCGI). Set inline_imagemaps to a true value to restore the original behavior. This can be done on a per-track basis or globally in [TRACK DEFAULTS].

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

feature_limit: This option will limit the number of features displayed in the track to a maximum. It can be useful in situations such as mRNA alignments where regions around highly-expressed genes contain orders of magnitude more features than typical regions. You may also place this option into [TRACK DEFAULTS] as a safety mechanism:

[TRACK DEFAULTS]
feature_limit = 500

visible: This option controls the default visibility of the track and is one of show, hide or collapsed. If present, it overrides the general "default tracks" setting.

label density: This is a numeric option. When there are more features visible in the track than the indicated number, their labels will be turned off to save space. This can be overridden by the user.

bump density: This is a numeric option. When there are more features than the number indicated, vertical collision control will be turned off; all features will be confined to a single horizontal line at the top of the track. This can be overridden by the user.

show summary: This is a numeric option. When the region being displayed is larger than the indicated length (in base pairs), then the track will go into summary mode and show a density gram of the number of features in the track. This will greatly speed up the display of dense tracks over large regions and increases legibility. A value of zero disables summary mode. See Summary Mode for more information.

bump: This option controls the packing of features. Possible values are:

0        no collision control
1        ordinary collision control; optimal tight packing applied to minimize wasted space
2        simple packing - each feature occupies separate vertical band
fast     faster packing which works best when all features are exactly same height
overlap  strand-specific collision control, and features are render translucent to allow the overlap to be seen

"overlap" bumping (version 2.46 and higher) is designed chiefly for quantitative (xyplot) tracks to show the overlap of quantitative peaks. It is usually combined with the "opacity" and "color_series" options.

The way strand-specific collision control works is that if two features are on the same strand, then they overlap with each other. If they are on different strands, then collision-control goes into effect. This gives you two horizontal bands, one for forward strand features, and one for negative strand features, and is a quick-and-dirty way to create composite features, such as coding genes and their regulatory elements.

opacity (version 2.46 and higher): This controls the opacity applied to features that collide using "bump=overlap". It is a floating point value between 0.0 and 1.0, where 0.0 is completely transparent, and 1.0 is entirely opaque. The default is 0.3.

color_series (version 2.46 and higher): This option, if set to a true value, will cause GBrowse to assign background colors to features following a simple color series of (red blue green yellow orange brown aqua black fuchsia green lime maroon navy olive purple silver teal magenta). The color series is changeable using the color_cycle option. The option is usually used in conjunction quantitative tracks and "bump=overlap", so that superimposed xyplots are distinguishable on the basis of their color.

color_cycle (version 2.46 or higher): This option, when used in conjunction with color_series sets the series of colors that features within the track will cycle among. It is a space-delimited set of Bio::Graphics-style colors.

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 GBrowse2 Admin Tutorial for more details.

subtrack select, subtrack table, subtrack labels (new in 2.10)

Subtrack selector

These three options together allow you to create a series of named subtracks within a track. The user will be able to individually hide and show the subtracks, as well as to control their order using the user interface shown in the figure to the right. It is currently most useful for organizing a set of single features that span the entire chromosome, such as wiggle tracks.

See Creating Subtracks for a full description of subtrack creation and manipulation.

select (deprecated)

This is an older version of the subtrack creation mechanism, which is still supported for backward compatibility. See Creating Subtracks for the preferred way of doing this.

The form of the "select" 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:

Variable Name	Value
$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 targeting 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

Subtrack Creation Options

Several options allow you to declare and configure subtracks, which are sets of filtered features organized within band inside the main tracks. These are described at length in Creating and Managing Subtracks with GBrowse2.

metadata

If the track contains a small number of features that have distinct display names, such as a set of quantitative (wiggle) features, then use this option to associate an auxiliary "metadata" file with the features contained in this track. The metadata file describes each feature's distinguishing attributes and allows the user to select among them. See Creating and Managing Subtracks with GBrowse2 for yhe file gormat and a worked example.

subtrack select

If, on the other hand, the track contains a large number of features and it is impractical to enumerate them by hand, then use this option to define subtrack filters. Each filter becomes a heading in the subtrack selection dialog box, and combination of filters listed in the subtrack table option define each subtrack.

Each filter declaration consists of two to three white-space separated values, terminated by a semicolon. The first value is the column label. The second column is a method call name to be applied to the feature (discussed at more length later). The optional third argument is an argument to be passed to the method call.

The method name can be any of the methods accepted by Bio::SeqFeatureI feature objects. Typical methods used for the second argument are "display_name" (the name of the feature), "type", "method", "source", "score", "strand", "has_tag", and "tag_value". "has_tag" and "tag_value" both require the third argument to determine which tag to interrogate.

Example:

subtrack select = Strand strand ;
                  Status tag_value status

This configuration will apply two filters to each feature to sort them into subtracks. The Strand filter will invoke each feature's strand() method, and the Status filter with call each feature's tag_value() method with an argument of "status", i.e. $feature->tag_value('status').

subtrack table

This option defines the values that the dimensions can take on and specifies how to partition them into subtracks. Lines are separated by semicolons. Within each line are a series of values to be matched against the dimensions specified by "subtrack select" in the following format:

:subtrack_label matchval1 matchval2 matchval3... =id *

The match values are required and must number the same as the dimension filters given in subtrack select. The optional :subtrack label assigns a human-readable label to the subtrack for display purposes. The ":" character will not be displayed. =id assigns an ID to the subtrack for use when turning tracks on and off in the GBrowse URL. The "*" character, if present, will turn this subtrack on by default when the user loads the track for the very first time.

When performing the match, values in this table that look like numbers will be compared using a numeric match. Otherwise they will be compared using a case sensitive exact string match. Values that are proceeded by the ~ symbol (e.g. "~abc") will be matched using a case-insensitive regular expression match.

Example:

subtrack table = :"+Strand Curated"    +1 confirmed =fc * ;
                 :"-Strand Curated"    -1 confirmed =rc * ;
                 :"+Strand Predicted"  +1 predicted =fp   ;
                 :"-Strand Predicted"  -1 predicted =rp

The subtrack table option can also be used to highlight one type of feature in a larger collection and assign all others to a separate sub track. The example below filters features by their source tag. All features with a source other than "SpecialSource" will be assigned to the "Other" sub-track.

subtrack select = Source source
subtrack table  = :SpecialLabel SpecialSource;
                  :Other 0;

brief comment: This optional option is a bit of explanatory text to insert at the top of the subtrack selection dialog.

subtrack labels

If you would like to select subtracks based on its type, a tag, or some other method, but you want the user to see a different label for the value when it is displayed in the subtrack selection dialog, you can specify the label here. For example, if you wish the +1 and -1 values in the example above to be displayed using the terms "Forward" and "Reverse", you would define that this way.

subtrack labels = +1 "Forward" ;
                  -1 "Reverse"

hide empty subtracks: If this option is set to a true value, then subtracks that do not contain any data in currently viewed region will be suppressed. Otherwise, their titles will be printed and they will take up a small amount of blank vertical real estate.

See Creating and Managing Subtracks with GBrowse2 for more information.

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(This section has been edited - "feature" line has been removed from the remaining stanzas):

  [gene]
  feature = transcript:curated
  glyph    = dna
  fgcolor  = blue
  key      = genes
  citation = example semantic zoom track

  [gene:500]
  glyph   = gene

  [gene:100000]
  glyph   = arrow

  [gene:500000]
  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

Summary Mode (new in version 2.09)

Normal mode: each feature is rendered separately

Summary mode: a density plot shows the number of features per interval

Summary Mode, which was introduced in version 2.09, is a form of semantic zooming in which the regular display of individual features is replaced by a density graph or histogram showing the number of features across the displayed region. Because the rendering is very fast, users can zoom out to view the entire chromosome without waiting for a long redisplay. The two figures to the right show how a track appears in regular and summary mode.

There are certain limitations on summary mode:

It only works with Bio::DB::SeqFeature::Store databases, although support for the Chado and Bio::DB::GFF adaptors is pending. It does work with all flavors of Bio::DB::SeqFeature::Store, including the in-memory and Berkeleydb implementations.
You will need BioPerl version 1.6.2 or higher. The currently released version of BioPerl is 1.6.1, so you will need to get a newer version from the BioPerl source code repository (see below).
Bio::DB::SeqFeature::Store databases created with older versions of BioPerl will need to be upgraded to support summary mode. This is done easily and quickly with a command-line utility described below. The databases created by newer versions of BioPerl support summary mode automatically.

Step-by-step instructions:

Install the development version of BioPerl

Download the latest "snapshot" of BioPerl from The BioPerl Web Site. Alternatively, you may use the "git" source code control command to make a local copy of the developers' repository. This will enable you to update BioPerl regularly. See [for downloading BioPerl via Github]. Follow the directions to run "perl Build.PL; Build; Build install".

Upgrade preexisting Bio::DB::SeqFeature::Store databases

You will need to upgrade your preexisting databases to take advantage of summary mode. This is done using the bp_seqfeature_load.pl script with the --summary command line option. Make sure you are using the new version of the script that comes with the developer's release of BioPerl.

For a MySQL database named "my_genome" located on the localhost:

 bp_seqfeature_load.pl -a DBI::mysql -d my_genome --summary

The same, but with a username and password:

 bp_seqfeature_load.pl -a DBI::mysql -d my_genome -u myname -p secret --summary

The same, but on a remote host named "beehive":

 bp_seqfeature_load.pl -a DBI::mysql -d my_genome:host=beehive -u myname -p secret --summary

A SQLite database located at /usr/local/share/my_genome.sqlite:

 bp_seqfeature_load.pl -a DBI::SQLite -d /usr/local/share/my_genome.sqlite --summary

A Berkeleydb database located at /usr/local/share/my_genome.berkeley:

 bp_seqfeature_load.pl -a berkeleydb -d /usr/local/share/my_genome.berkeley --summary

In-memory databases do not need to be upgraded, nor do new databases created by bp_seqfeature_load.pl with the --create option.

Enable summary mode in your datasource configuration file(s)

Insert the show summary option within the [TRACK DEFAULTS] stanza:

[TRACK DEFAULTS]
 ...
 show summary = 1000000

The value of "show summary" specifies the region length, in base pairs, at which to switch into summary mode. The example above specifies to switch into summary mode at a level of 1 Mb or higher (1,000,000 bp), but the appropriate value will be depend on the genome size and average number of features per chromosome.

You may change this value on a track-by-track basis by adding "show summary" options to the track stanzas you wish to override. To turn summary mode off completely for a track, either set the value to something ridiculously high, or specify a value of "0".

Creating Subtracks (new in version 2.09)

You can create an unlimited number of subtracks within a single major track in order to group a series of datasets that are logically linked, such as a timecourse. You can choose which subtracks to show by default and the order in which they will appear. The user can use a dialog box to select which subtracks to make visible and to reorder the subtracks.

See Creating and Managing Subtracks with GBrowse2 for full details.

Advanced Datasource Configuration Topics

This section describes how to further customize your GBrowse data sources to provide for an exceptional end-user experience.

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 Bio::Graphics::Feature and Bio::SeqFeature::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

Using Pipes in the GBrowse.conf Data Source Name

It is sometimes convenient to generate datasource files programatically rather than using a static file. To do this, you can give GBrowse.conf a "path" option that uses Perl's "piped open" syntax to read the output of a script. For example:

 # this is in GBrowse.conf
 [modENCODE_preview]
 description = modENCODE preview database
 path        = /usr/local/modencode/bin/preview.pl |

The script (preview.pl in this example) must print a correctly formatted GBrowse datasource configuration file to its standard output.

[Available in 2.09 and higher] To get even more elaborate than this, you can use a regular expression as the stanza datasource name, allowing you to pass extracted subexpressions to the script. For example:

[=~modENCODE_preview_v(\d+)]
 description = modENCODE preview database
 path        = /usr/local/modencode/bin/preview.pl $1 |

The "=~" prefix is required to turn on regular expression scanning. This will match any data source of the format "modENCODE_preview_v123" where "123" is a series of digits. The digits will be extracted using the regular expression and passed to preview.pl as an argument:

/usr/local/modencode/bin/preview.pl 123 |

You can then invoke GBrowse with any of the following URLs and have the indicated script return the appropriate data source configuration data on its standard output:

http: //your.host/gb2/gbrowse/modENCODE_preview_v1
http: //your.host/gb2/gbrowse/modENCODE_preview_v2
http: //your.host/gb2/gbrowse/modENCODE_preview_v42

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;
     }

Restricting Access to Data Sources and Tracks with Usernames and Passwords

See: GBrowse Configuration/Authentication

Configuring Balloon Tooltips

See: GBrowse Configuration/Balloons.

Generating Static Images: PNGs, SVGs and PDFs

See: GBrowse Configuration/Images.

Describing a GBrowse data source using structured meta-data

If you wish, you can enter options into the datasource config file that will described the data in a structured way. This in turn can be used by automated scripts to discover the species, genomic build, the name of the maintainer, and other descriptive information about the data source. The information is compatible with the DAS Registration server and in a coming GBrowse release will allow GBrowse instances to automatically register themselves so that users and automated scripts can easily find and extract information from the browser.

To enter metadata about a particular data source, go to the [GENERAL] section of its configuration file and enter a metadata option formatted like this one:

 metadata =
        -description             Example GBrowse database containing information from WormBase
				 (www.wormbase.org) and modENCODE (www.modencode.org).
        -maintainer              Lincoln Stein <lincoln.stein@gmail.com>
        -created                 2010-1-4
        -modified                2009-9-1
        -authority               WS
        -coordinates_version     180
        -coordinates             http://www.dasregistry.org/coordsys/CS_DS109
        -source                  Chromosome
        -testrange               I:7385068..7387651
        -species                 Caenorhabditis elegans
        -taxid                   6239

The metadata option has multiple suboptions (note the required leading whitespace in front of them):

-description: A free text description of the data source. It can span multiple lines.
-maintainer: An email address for the person or mailing list to contact concerning issues with the data source.
-created,-modified: The creation and modification date of the resource, in the format YYYY-MM-DD.
-authority,-coordinates_version and -coordinates: These fields establish the genome build and build version. The authority is a short prefix indicating the organization that is responsible for the build, such as "NCBI" (human), "WS" (WormBase), or SGD (Yeast), and coordinates_version indicates the version of the build. In the example above, therefore, the build is described as WS180. For greatest power, you can use -coordinates to provide a DAS registry coordinate system URL so that software that uses the DAS system can reliably combine tracks from different data sources. Many coordinate systems are already registered at the DAS registry; you may register a new one if needed.
-source: This describes the type of coordinate system used, either "Chromosome" or "Contig".
-testrange: This provides an example range for new users to look at.
-species,-taxid: These indicate the species name (in long binomial format) and the NCBI taxon id.

Note that the support for automatic registration and discovery of GBrowse data sources is not available in the 2.00 release, but is expected to be added in a subsequent point release.

Advanced Configuration Topics

Maintaining the User Accounts Database

If you have the requisite modules installed (DBI, DBD::SQLite or DBD::mysql), then ./Build install will run a script called "gbrowse_metadb_config.pl", which creates and initializes a user account database for managing user logins and shared tracks. If you take advantage of the user accounts feature (described in more detail in GBrowse_Configuration/Authentication), you may wish to run gbrowse_metadb_config.pl periodically. It checks for database inconsistencies, removes unused uploads, and does other routine maintenance on the user accounts database.

Removing Unused Sessions, Uploads and Cached Images

Over time GBrowse will accumulate unused sessions left by users who visit once and never return. Eventually these unused sessions will use up disk space and may adversely affect performance. The same issue affects custom tracks (uploaded files) and cached images.

You can clean up these files using the Unix "find" command:

    cd /var/tmp/gbrowse2
    sudo -u www-data find . -type f -atime +20 -print -exec rm {} \;

This will remove all files that have not been accessed for more than 20 days. Note that the command should run as the Apache web user ("www-data" in this example). The number of days is specified with -atime +20. Change 20 to some other value if you desire.

You may wish to run this as a daily cron job, either by adding it to the web user's cron table, or by running it in root's cron table.

The GBrowse2 REST API

See: GBrowse2 REST API (section under construction)

@@ Line 1: / Line 1: @@
-<div style="background-color: lightblue" >
-'''Important note:''' GBrowse 2.0 has not been released yet and is only available from [[CVS_Access|CVS]]. The software will be released as a tar file for beta test soon after this documentation is completed.
-</div>
-=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.
+*'''User Interface:''' The user interface uses {{GlossaryLink|AJAX|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.
@@ Line 16: / Line 10: @@
 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 | 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).
+This section describes the various ways to get GBrowse up and running.
-First, save the distribution archive (GBrowse-2.00.tar.gz) to a convenient place, and then unpack it using the '''tar''' and/or '''gunzip''' programs. In this and all subsequent examples, the commands you type are in '''bold'''.
+==GBrowse Virtual Machines==
- % '''tar zxvf ~/projects/Generic-Genome-Browser-Trunk/GBrowse-2.00.tar.gz'''
+The easiest way to get started using GBrowse2 is to use one of the pre-packaged virtual machines with all libraries, tools and other dependencies preinstalled. There are two standard GBrowse VMs, one for running on your desktop using [http://www.virtualbox.org VirtualBox], and the other for running on [http://aws.amazon.com Amazon Web Services].
- GBrowse-2.00/
- GBrowse-2.00/t/
- GBrowse-2.00/t/05.deferredrendering.t
- GBrowse-2.00/t/06.featuresearch.t
- GBrowse-2.00/t/01yeast.t
- GBrowse-2.00/t/07.karotype.t
-Next, enter the newly-created directory and run the Build.PL script:
+Please see [[GBrowse2 VMs]] for a list of the VMs that are available to use, plus a quick start guide to using these virtual machines.
-<pre>
+==Ubuntu 11.10 and higher Binary Installs==
- % '''perl Build.PL'''
- Checking whether your kit is complete...
- Looks good
- Checking prerequisites...
+In Ubuntu versions 11.10 and higher, you can install GBrowse2 and all its dependencies from the Software Center or from the command line. From the Software Center, search for "gbrowse" and click the "install" button. You may also wish to install the "gbrowse_data" package, which includes example data files and tutorials.
- 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
+From the command line, run the following:
- cc -shared -L/usr/local/lib -o /tmp/compilet.so /tmp/compilet.o
-  Creating new 'Build' script for 'GBrowse' version '2.00'
+  > apt-get install gbrowse gbrowse_data
- Now run:
-  ./Build test
-  ./Build config
-  ./Build demo          (optional)
-  ./Build install       (as superuser/administrator)
-        -or-
-  ./Build install_slave (optional, for slave installations)
-</pre>
-{| align="right" class="toc" style="margin-left: 0.5em; width: 20em; background-color: lightblue"
+==Debian "sid" Binary Installs==
-|- align="center" style="font-size: 115%; font-weight: bold"
-|
-Note: BioPerl issues
-|-
-|
-One prerequisite that is not available from CPAN is BioPerl. GBrowse requires version 1.5.2 of BioPerl, but so far only version 1.4 has been released to CPAN. You will need to go to the BioPerl download page, and unpack and install BioPerl manually. Because 1.5.2 is officially a developer release, you may not wish to install it into your system files. In this case, you can simply unpack it into some convenient location (your home directory or elsewhere), and configure GBrowse to find it by invoking Build.PL this way:
- % perl -I /home/fred/packages/bioperl-1.5.2 Build.PL
+In Debian and Debian-related systems, run the following command:
-Replace /home/fred/packages/bioperl-1.5.2 with the path to the unpacked BioPerl distribution. Henceforth, GBrowse and all its support scripts will know to look in this directory to find BioPerl. Once you choose a location for BioPerl, do not move or rename it.
+ >aptitude install gbrowse gbrowse_data
-|}
-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 [http://www.cpan.org CPAN] or installed from the command line using the [http://www.perl.com/doc/manual/html/lib/CPAN.html CPAN shell]. There are also Debian and RPM installer packages for these libraries. See [[GBrowse 2.0 Prerequisites]] for full details.
+You might also wish to browse the [http://packages.debian.org/source/sid/gbrowse GBrowse Debian package pages.]
-This will create a script named ''Build'' in the current directory. 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:
+The current version in the Debian package is 2.39, which is a bit old but quite stable. The package will be updated at some point in the not-so-distant future.
-<pre>
+==Debian "wheezy" Binary Installs==
- % '''./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
-</pre>
-All tests should pass (you may safely ignore warnings and occasional timeout errors). If not, please file a [http://sourceforge.net/tracker/?func=add&group_id=27707&atid=391291 bug report], and/or send an inquiry to the [https://lists.sourceforge.net/lists/listinfo/gmod-gbrowse GBrowse mailing list].
+In Debian and Debian-related systems, run the following command:
-After passings its tests, you should configure GBrowse by running '''./Build config''':
+>aptitude install gbrowse gbrowse-data gbrowse-calign
-<pre>
+You might also wish to browse the [http://packages.debian.org/source/wheezy/gbrowse GBrowse Debian package pages.]
- % '''./Build config'''
- **Beginning interactive configuration**
+==Installation on Older Ubuntu and Debian Systems==
- 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**
+First install prerequisites following the instructions at [[GBrowse_2.0_Prerequisites#DEB Systems (apt)]]. Then perform the last steps manually as described in [[GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell]].
-</pre>
-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.
+==Installation on RedHat, CentOS and other RPM Systems==
-The configuration options are:
+First install prerequisites following the instructions at [[GBrowse_2.0_Prerequisites#RPM Systems (yum)]]. Then perform the last steps using the CPAN shell as described in [[GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell]].
-;apachemodules
+==Installation on MacOSX Systems==
-: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 be something like "/usr/lib/cgi-bin/gb2/gbrowse".
-;conf
-:The location of GBrowse's configuration files. The default is to place them in the "GBrowse2" subdirectory of ''/etc''. This is where you will go to customize GBrowse and add new data sources.
-;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.
-;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.
-;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:
+Install the prerequisites following the instructions at [[GBrowse_2.0_Prerequisites#MacOSX]]. Then perform the last steps using the CPAN shell as described in [[GBrowse_2.0_Install_HOWTO#Installing_via_the_CPAN_Shell]] and [[GBrowse_2.0_Install_HOWTO#Configure_in_Mac_OS_X_10.6.6]].
- perl Build.PL --apachemodules=/usr/local/share/apache/libexec \
+==Installation from Source Code==
-               --cgibin=/var/lib/cgi \
-               --conf=/etc/gbrowse \
-               --htdocs=/usr/local/docs \
-               --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''.
+Installation from source code is described in [[GBrowse_2.0_Install_HOWTO#Installing_Manually]].
-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'':
+==Users of GBrowse 1.X==
- % ./Build demo
+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.
- 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.
-To install GBrowse and its support files permanently, run ''./Build install''. This will copy GBrowse's library and support files into the locations chosen during configuration.
-The final step is to reconfigure Apache itself to run GBrowse. There is a small set of configuration options that need to be cut and paste into Apache's configuration file. To generate these options, run ''./Build apache_conf''. This will print a set of Apache configuration options to the screen:
-<pre>
-% ./Build apache_conf
-INSTRUCTIONS: Cut this where indicated and paste it into your Apache
-configuration file. You may wish to save it separately and include it
-using the Apache "Include /path/to/file" directive.
-===>>> cut here <<<===
-Alias "/gbrowse2/" "/var/www/gbrowse2/"
-<Location "/gbrowse2/">
-  Options Indexes FollowSymLinks MultiViews
-</Location>
-<Directory "/usr/lib/cgi-bin">
-  SetEnv GBROWSE_MASTER GBrowse.conf
-  SetEnv GBROWSE_CONF   "/etc/GBrowse2"
-  SetEnv GBROWSE_DOCS   "/var/www/gbrowse2"
-  SetEnv GBROWSE_ROOT   "/gbrowse2"
-  SetEnv PERL5LIB /home/fred/packages/bioperl-1.5.2
-  AllowOverride None
-  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
-  Order allow,deny
-  Allow from all
-</Directory>
-===>>> cut here <<<===
-</pre>
-You should now cut out the indicated section and paste it into the appropriate Apache configuration file. Typically this is a file named ''httpd.conf'' or ''apache.conf'' located in /etc/apache, /etc/httpd or /usr/local/apache/conf (linux and MacOSX), or ''C:/Program Files/Apache Software Foundation/Apache2*/conf'' under Windows. Because httpd.conf gets updated by vendors on a regular basis, you may wish to put the GBrowse-specific directives in a separate configuration file and then point Apache at them by placing something like the followint at the bottom of ''httpd.conf:''
+For GBrowse 1.X configuration, see: [[GBrowse Configuration HOWTO]].
-  # at the bottom of httpd.conf
+=Configuring GBrowse=
-  Include /path/to/gbrowse_directives.conf
-You can now restart Apache using the appropriate administration script.
+GBrowse is controlled by a set of text configuration files. You will log into the web server machine and edit these files using a text editor. Alternatively you can use
+[http://webgbrowse.cgb.indiana.edu WebGBrowse], which is a web-based system for initializing, configuring and customizing GBrowse databases. It is an add-on to GBrowse and should only be installed after GBrowse is up and running.
-=Customizing GBrowse=
+This section discusses manual editing of GBrowse's configuration files.
-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's options are controlled by a master config file, ''GBrowse.conf'' which contains site-specific options that apply to all data sources, and one or more ''Data source-specific'' configuration files that 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:
+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.
@@ Line 199: / Line 93: @@
 [GENERAL]
-config_base            = /etc/GBrowse2      # overriden by environment variable GBROWSE_CONF
+config_base            = /etc/gbrowse2   # overridden by environment variable GBROWSE_CONF
-htdocs_base            = /var/www/gbrowse2  # overriden by environment variable GBROWSE_HTDOCS
+htdocs_base            = /var/www/gbrowse2
-url_base               = /gbrowse2          # overriden by environment variable GBROWSE_ROOT
+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
-tmpimages     = tmp
 gbrowse_help  = .
-images        = images
 js            = js
@@ Line 217: / Line 111: @@
 moby_path      = MobyServices
-# balloon settings
+# session settings
-balloon tips         = 1
+session lock type = default
-titles are balloons  = 1
+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
@@ Line 227: / Line 127: @@
 # Performance settings
-cache time             = 2h
+renderfarm             = 1
 slave_timeout          = 45
 global_timeout         = 60
-remember_source_time   = +3M
-remember_settings_time = +1M
-url_fetch_timeout      = 5
-url_fetch_max_size     = 1000000
-too many landmarks     = 100
-# session settings
+# Clean up settings (used by the gbrowse_clean script)
-session driver = driver:file;serializer:default
+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
+#truetype      = 1    # use truetype fonts for rendering tracks; disabled by default.
+# 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
-# Appearance (can be overridden in per datasource config files)
+instructions section   = open
-# the stylesheet is relative to url_base if not otherwise noted
+upload_tracks section  = closed
-stylesheet        = css/gbrowse.css
+search section         = open
-plugins           = FastaDumper RestrictionAnnotator SequenceDumper Submitter
+overview section       = open
-overview grid     = 0
+region section         = open
-overview bgcolor  = lightblue
+detail section         = open
-detail grid       = 1
+tracks section         = open
-detail bgcolor    = lightgoldenrodyellow
+display_settings section = closed
-key bgcolor       = beige
-show track categories = 0
-image widths         = 450 640 800 1024
-default width        = 800
-pad_left             = 60
-pad_right            = 30
 # where to link to when user clicks in detailed view
@@ Line 264: / Line 177: @@
 # At the footer
-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
@@ Line 281: / Line 200: @@
 region sizes           = 1000 5000 10000 20000
 default region         = 5000
+fine zoom              = 10%
 # 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
 ###############################################################################################
@@ Line 303: / Line 211: @@
 #
 ###############################################################################################
-default source = yeast_chr1
+default source = yeast
-[yeast_chr1]
+[yeast]
-description   = S. cerevisiae chromosome I only
+description   = Yeast chromosomes 1+2 (basic)
-path          = yeast_chr1.conf
+path          = yeast_simple.conf
-</pre>
-'''GBrowse.conf''' consists of several sections. The [GENERAL] section is by far 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_chr1]. Each of these short sections describes a genome datasource which you make available for browsing.
+[yeast_advanced]
+description   = Yeast chromosomes 1+2 (advanced)
+path          = yeast_chr1+2.conf
-===The GBrowse.conf [GENERAL] Section===
+[renderfarm]
+description  = Renderfarm demo (gbrowse_slave must be running!)
+path         = yeast_renderfarm.conf
+</pre>
-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.
+'''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.
-;'''config_base''', '''htdocs_base''', '''url_base'''
+There are two '''include''' directives that allow you to break up GBrowse configuration files into smaller logically-related bits. The directive:
-:The first three options describe the location of GBrowse's configuration and support files. '''config_base''' is the location of GBrowse's configuration files, usually ''/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''.
-:These three configuration options are somewhat unusual in that they are overridden by the environment variables '''GBROWSE_CONF''', '''GBROWSE_HTDOCS''' and '''GBROWSE_ROOT''' respectively. These environment variables are usually set during Apache server startup in the apache configuration file as described earlier in the installation section.
+  #include "path/to/file"
-;'''buttons''','''balloons''','''gbrowse_help''','''js'''
+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.
-: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''', and if you specify a relative path, they will be taken as relative to '''htdocs_base''' (in filesystem space) and '''url_base''' (in URL space).
-==The [GENERAL] Section==
+The directive:
-The [GENERAL] section consists of a series of name=value options. For example, the beginning of the yeast.conf sample configuration file looks like this:
+ #exec "/usr/bin/script_to_execute"
- [GENERAL]
+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.
- description = S. cerevisiae (via SGD Nov 2001)
- db_adaptor  = Bio::DB::GFF
- db_args     = -adaptor dbi::mysql
-               -dsn     dbi:mysql:database=yeast;host=localhost
- aggregators = transcript alignment
- user        =
- passwd      =
-Each option is a single word or phrase, usually in lower case. This is followed by an equals sign and the value of the option. You can add whitespace around the equals sign in order to increase readability. If a value is very long, you can continue it on additional lines provided that you put a tab or other whitespace on the continuation lines. For example:
+===The GBrowse.conf [GENERAL] Section===
- description = S. cerevisiae annotations via SGD Nov 2001, and
+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.
-             converted using the process_sgd.pl script
-Any lines that begin with a pound sign (#) are considered comments and ignored.
+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'').
-During this discussion, you might want to follow along with one of the example configuration files.
+====Paths and Directories====
-The following [GENERAL] options are recognized:
+;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 <nowiki>http://your.site/GBrowse</nowiki>, 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.
-*'''description'''
+: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.
-The description of the database. This will appear in the popup menu that allows users to select the data source and in the header of the page. Don't make it as long as the previous example! (You will want to change this.)
-*'''db_adaptor'''
+;buttons, balloons, gbrowse_help, js
-Tells GBrowse what database adaptor to use. By using different adaptors you can attach gbrowse to a variety of different databases. Currently the only stable adaptor you can use is Bio::DB::GFF, which is a standard set of adaptors contained in Bioperl.
+: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).
-*'''db_args'''
+;plugin_path, language_path, templates_path, moby_path
-Arguments to pass to the adaptor for it to use when making a database connection. The exact format will depend on the adaptor you're using. For Bio::DB::GFF running on top of a MySQL database use a db_args like the following:
+:These configuration options specify where [[GBrowse Plugins | plugins]], language translation files, templates and [http://www.biomoby.org 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'''.
-    db_args = -adaptor dbi::mysql
+====Session Settings====
-              -dsn     dbi:mysql:database=<db_name>;host=<db_host>
-replacing <db_name> and <db_host> with the database and database host of your choice. For MySQL databases running on the localhost, you can shorten this to just "db_name".
+;session driver, session args
+<div class="indent">
+These two options pass settings to the {{CPAN|CGI::Session}} module, which is responsible for GBrowse's persistent user settings. As described in the {{CPAN|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:
-If the database requires you to log in with a user name and password, use the following db_adaptor:
+  session driver = driver:db_file;serializer:default
+  session args   = FileName /var/tmp/gbrowse2/sessions.db
+</div>
+;session lock type
+<div class="indent">
+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:
-    db_args = -adaptor dbi::mysql
+;flock
-              -dsn     dbi:mysql:database=<db_name>;host=<db_host>
+: 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.
-              -user    <username>
-              -pass    <password>
-replacing <username> and <password> with the appropriate values. In the example configuration files, we use a username of "nobody" and an empty password. This is appropriate if the database is configured to allow "nobody" to log in from the local machine without using a password.
+;nfs
+: Use the File::NFSLock module for locking. This is fast and works across NFS, but requires you to install the {{CPAN|File::NFSLock}} module from CPAN.
-To use the Oracle version of Bio::DB::GFF, use these arguments:
+; 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:
+:: <pre>session lock type = mysql:dbi:mysql:my_db;host=hostname;port=portnum;user=user;password=pass</pre>
+: for simplicity, you can leave off the initial "mysql:".
-    db_args = -adaptor dbi::oracle
+:A value of '''default''' will choose the File::NFSLock module if it is available, and otherwise fall back onto standard flock.
-              -dsn dbi:oracle:database=db_service
+</div>
-Where db_description should be replaced with the name of the desired database service definition. See the documentation for the Perl dbd::Oracle database driver for more information about the -dsn format.
+====Performance Settings====
-To use the in-memory version of Bio::DB::GFF, use these arguments:
+This section contains a variety of performance-related settings that you may want to change in order to tune GBrowse for your needs.
-  db_args = -adaptor memory
+;renderfarm
-            -dir   /path/to/directory
+<div class="indent">
+This configuration directive turns on and off GBrowse's support for a rendering farm (see [[Running_a_GBrowse2_render_farm | 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:
-The indicated directory should contain one or more GFF and FASTA files, distinguished by the filename extensions .gff and .fa respectively.
+  renderfarm = 0
+</div>
-*'''allow remote callbacks'''
+;slave_timeout
-This option, if true, allows users to place callbacks ("sub ....") in the configuration sections of uploaded files.The callbacks will be executed in a Safe::World compartment, which forbids access to the file system, dangerous operations such as "exec" and "eval", and access to anything but the Bio::Graphics::SeqFeature and Bio::Graphics::Glyph classes. The option also affects remote annotation tracks. For this option to work, the Safe::World module must be installed from CPAN.
+: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.
-*'''aggregators'''
+;global_timeout
-This option is only valid when used with Bio::DB::GFF adaptors, and lists one or more aggregators to use for complex features. It is possible to declare your own aggregator here using a special syntax described in "B7. Declaring New Aggregators."
+: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.
-To disable the default aggregators, leave this setting blank, as in:
+;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 {{CPAN|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.''
-     aggregators=
+;max_render_processes
+<div class="indent">
+GBrowse launches a subprocess for each track it renders. This option will limit the number of simultaneous subprocesses that can be launched in order to avoid overloading the system. The default is four; you may wish to adjust this upward on a system with 4 or more CPUs. A good choice is between one and two times the number of CPUs/cores on the server system:
-To activate the default aggregators of "transcript," "clone," and "alignment," comment this setting out entirely:
+ max_render_processes = 8
+</div>
-    # aggregators =
+====Appearance Settings====
-Do not use aggregators with Bio::DB::SeqFeature::Store, BioSQL, or Chado.
+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.
-*'''user'''
+;autocomplete
-The user name for the gbrowse script to log in under if you are not using "nobody". This is exactly the same as providing the -user option to db_args, and is deprecated.
+: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|Database Search Options]] for more information.
-*'''pass'''
+:The autocomplete setting also applies to the "Custom Tracks" and "Community Tracks" sections, and allows users to search the user account database for public tracks via autocomplete. See [[GBrowse_Configuration/Authentication]] for more information on the user account database.
-The password to use if the database is password protected. This is the same as providing the -pass option to db_args, and is deprecated.
-*'''gbrowse root'''
+;balloon tips
-This specifies the URL of GBrowse's static files on your server, such as stylesheets, images and JavaScript files. The default is /gbrowse.
+: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.
-*'''stylesheet'''
+;titles are balloons
-Location of the stylesheet used to create the GBrowse look and feel. You can give a relative address (e.g. "gbrowse.css"), in which case GBrowse will look relative to the URL specified by "gbrowse root." Alternatively, you can specify an absolute URL (e.g. "/stylesheets/mysite.css").
+: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.
-*'''buttons'''
+;stylesheet
-URL in which the various graphical buttons used by GBrowse are located. The relative and absolute addressing rules described for "stylesheet" apply here as well. (You will probably not need to change this.)
+<div class="indent">
+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.
-*'''js'''
+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:
-URL in which the gbrowse javascript helper function files are located. The relative and absolute addressing rules described for "stylesheet" apply here as well. (You will probably not need to change this).
+<pre>
+ stylesheet = css/gbrowse.css(screen)
+              http://www.example.com/hires.css(paper,projection)
+              http://www.example.com/audio.css(audio)
+</pre>
+</div>
-*'''tmpimages'''
+;truecolor
-URL of a writable directory in which GBrowse can write its temporary images. The format is:
+:If set to a true value, then the tracks will be rendered as full-color 24-bit images, improving appearance at the cost of larger images. The effect may be noticeable on a slow internet connection.
-  tmpimages = <tmpimages_url> <tmpimages_path>
+;truetype
+:If set to a true value, then the fonts in track images will be rendered using truetype fonts installed on the server. A value of "1" selects a safe default font. A string value can be used to select a particular font, such as "Droid Sans" or "Helvetica-9". This option only works on versions of GBrowse from 2.55 onward, and only if Bio::Graphics 2.33 or higher is installed.
-Where <tmpimages_url> is the directory as it appears as a URL and <tmpimages_path> is the physical path to the directory as it appears to the filesystem. Usually the physical path is just the URL with the DocumentRoot configuration variable prepended to it, in which case only the URL is needed. However, if the URL is defined using an Alias directive, then the path argument is mandatory.
+;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.
-The tmpimages option is mandatory.
+;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.
-The relative and absolute addressing rules described for "stylesheet" apply here as well.
+;image widths, default width
+<div class="indent">
+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.
-NOTE: The path argument is ignored if gbrowse is running under modperl, because modperl allows the URL to be translated into a physical directory programatically.
+ image widths    = 450 640 800 1024 1280
+ default width   = 1024
+</div>
-*'''plugins'''
+;pad_left, pad_right
-This is a list of plugins that you want to be available from gbrowse. Plugins are a way for third-party developers to add functionality to gbrowse without changing its core source code. Plugins are stored on the gbrowse configuration directory under a subdirectory named "plugins."
+: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 [[GBrowse_UCSC_Plugin_Install_HOWTO | UCSC multiple alignment glyph]].
-A good standard list of plugins is:
+;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.
-    plugins = SequenceDumper FastaDumper RestrictionAnnotator
+;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 [[:Glyphs_and_Glyph_Options#Colors|Bio::Graphics color value]], such as "beige:0.8" for a beige background at 80% opacity.
-See the contents of conf/plugins and contrib/plugins for more plugins that you can install.
+;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 [[:Glyphs_and_Glyph_Options#Colors|Bio::Graphics color value]], such as "red:0.8".
-*'''quicklink plugins'''
+;hilite height
-This is a list of plugins that you want to appear as links in the link bar (which includes the [Bookmark this] and [Link to Image] links). Selecting one of these links is equivalent to choosing the plugin from the popup menu and pressing the "Go" button. The popup will continue to appear in the popup menu.
+:This option controls the height of the draggable region marker, which highlights the currently selected region
-*'''plugin_path'''
+;overview bgcolor, region bgcolor, detail bgcolor
-By default gbrowse searches for plugins in its standard location of conf/plugins. You can store plugins in a non-standard location by providing this option with a space-delimited list of additional directories to search in.
+:These three options control the background colors of the overview, region and detail panels respectively. They each accept [[:Glyphs_and_Glyph_Options#Colors|Bio::Graphics color value]].
-*'''galaxy outgoing'''
+;grid color, grid major color
-If you would like GBrowse to be able to send data to the [http://main.g2.bx.psu.edu/ Galaxy bioinformatics analysis tool], then set this option to the URL for the Galaxy server you would like to use. A good default is:
+: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 [[:Glyphs_and_Glyph_Options#Colors|Bio::Graphics color value]].
-   galaxy outgoing = http://main.g2.bx.psu.edu/
+;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.
-Without this option, GBrowse will be able to receive and process queries from Galaxy servers, but will not be able to initiate a connection. (Note, this option used to be named "galaxy", which still works for backward compatibility)
+;instructions section, upload_tracks section, search section, overview section, region section, detail section, tracks section, display_settings section
+:These options control whether a section is toggled open initially ("open"), or toggled closed ("closed"). In addition, for the "overview section", "region section" and "detail section", you can specify a value of "hide" in which case the section isn't shown at all. Generally this only makes sense for the region section.
-*'''galaxy incoming'''
+;category default state
-Use this option to change the URL that Galaxy will use when it tries to fetch GFF3-formatted data from GBrowse. The default is:
+:As described in the track configuration section, a track can be placed in a category or subcategory. The categories can be toggled open and closed. The "category state" option, described next, allows you to configure the toggle state of each category and subcategory when the user first accesses the page. If a category is not explicitly named, then this option is consulted to find the default. Values are either "open" to make each category open by default, or "closed". For convenience, you may use the integer value 0 for "closed" or 1 for "open".
-   http://yourhostname/cgi-bin/gbgff
+;category state
+<div class="indent">
+This option controls whether a category or subcategory is open or closed when the user first visits the page, or resets his state with the "Reset" menu choice. The format is as shown in this example:
-However, the default will break if the Gbrowse web server is behind a web proxy that uses a different hostname. In this case, you will need to set the location of the gbgff script explicitly.
+ category state = Genes           open
+                  Genes:Coding    open
+                  Genes:Noncoding closed
-*'''galaxy build name'''
+Categories are identified by their names; subcategories and sub-subcategories are indicated by dividing the subcategories by ":" characters. You may use "open" to indicate that a category is open at first, or "closed" to collapse it on the first page load. "1" and "0" can be used instead of "open" and "closed".
+</div>
-To be most effective, Galaxy needs to know the genome build name corresponding to the annotations contained in the current database so that it can integrate GBrowse-generated data with other data sets. Each species has its own build name conventions, for example "hg18" for UCSC build number 18. Set this to the build name of your choice. If not present, the value default to the database name.
+====Fast Track Panning (new in version 2.20)====
-*'''hilite fill''', '''hilite outline'''
+This configures fast track panning, the ability for a user to drag/pan the details tracks back and forth to instantly see more of the image.  Extra wide images are preloaded from the server to accomplish this, so it may affect the initial image load time.
-These options control the color of the selection rectangles that appear in the overview and regionview when you are zoomed into a region. The hilite fill controls the color of the rectangle interior, and the hilite outline controls the color of the rectangle outline. Colors can be specified by name (e.g. "pink"), or in HTML #RRGGBB format.
+;details multiplier
+:How much extra image data to load.  A value of 3.0 means that three times the viewable image width will be loaded. The default is 1.0, which means that fast track panning is turned off and GBrowse behaves as usual.
-*'''image widths'''
+====Cleanup Settings====
-The image widths option controls the set of image sizes to offer the user. Its value is a space-delimited list of pixel widths. The default is probably fine. Note that the height of the image depends on the number of tracks and features, and cannot be controlled.
-*'''default width'''
+These settings are used by the [[gbrowse_clean.pl]] script to remove stale temporary files of various sorts.
-The default width is the image width to start off with when the user invokes the browser for the first time. The default is 800.
-*'''default features'''
+;expire cache
-The default features option is a space-delimited list of tracks to turn on by default. You will probably need to change this. For example:
+: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.
-     default features = Genes ORFs tRNAs Centromeres:overview
+;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.
-The syntax for annotation plugins is slightly different. To activate an annotation plugin track by default, preface the plugin's name with "plugin:"
+;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.
-     default features = Genes ORFs Centromeres:overview
+====Upload Database Settings====
-                        plugin:RestrictionAnnotator
-*reference class
+These options configure the backend database that is used to store the information that a user uploads when he or she creates custom tracks. The default is to choose a workable database system based on the Perl DBI drivers installed on the system. See [[GBrowse_2.0_Install_HOWTO/Advanced#Configuring the Uploaded Track Database|Configuring the Uploaded Track Database]] for detailed configuration information.
-gbrowse needs to know the class of the reference sequences that other features are placed on. The default is Sequence. If you want to use another class, such as Contig, please indicate the class here (if you don't, certain features such as the keyword search will fail):
-      reference class = contig
+;upload_db_adaptor
+:Which database backend to use for custom tracks. Valid options are "DBI::SQLite", "DBI::mysql", "berkeleydb" and "memory". The SQLite database backend combines great performance with little or no maintenance, but does require the perl {{CPAN|DBI::SQLite}} module to be installed. The memory backend requires no additional Perl modules, but is only appropriate for very small uploads (less than 10,000 features). The {{CPAN|DBI::mysql}} backend has the best performance, but needs additional configuration in order to make it possible for GBrowse to create and drop databases dynamically.
-*initial landmark
+;upload_db_host
-This option controls what feature to show when the user first visits a gbrowse database and has not yet performed a search. If not present, gbrowse displays a page with the search area and options, but no overview or panel.
+:When using the DBI::mysql backend, this specifies the host on which the mysql DBMS is running. (Default "localhost").
-Example:
+;upload_db_user
+:When using the DBI::mysql backend, this specifies the user that has access to the mysql server. This user must have database create/drop privileges for databases beginning with the string "userdata_". (Default "gbrowse").
-       initial landmark = Chr1
+;upload_db_pass
+:When using the DBI::mysql backend, this specifies the password for the user named by '''upload_db_user'''. (Default no password).
-*'''drag and drop'''
+;admin_account
-If this is set to true, then code will be activated that lets the user pick up and drag individual tracks in order to change their vertical stacking order. For this to work, the user must have a relatively recent browser (IE 5 or higher, Firefox 1.5 or higher) and must have JavaScript activated.
+:The name of the administrator account that has privileges to upload and configure public tracks. See [[GBrowse 2.0 Install HOWTO/Advanced#The Admin Interface|The Admin Interface]] for more details.
-It is off by default for compatibility with older browsers.
+;admin_dbs
+:The path used to store data files uploaded by the administrator named in '''admin_account'''. See [[GBrowse 2.0 Install HOWTO/Advanced#The Admin Interface|The Admin Interface]] for more details.
-*'''disable wildcards'''
+====Debug Settings====
-Ordinarily a user can type in "YAL*" to find all features with names beginning with "YAL". This option, if set to a true value, disables wildcard searching.
-*'''truecolor'''
+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.
-If this option is present and true, then GBrowse will create 24-bit (truecolor) images. This is mainly useful when using the "image" glyph, which allows you to paste arbitrary images onto the genome map. Do not use this option unless you need it, because it slows down drawing and makes the images much larger.
-*'''units''', '''unit_divider'''
+;debug
-The units option allows GBrowse to display units on an alternate scale (for example, (centi)Morgans), and the unit_divider provides the converstion factor between base pair units (which is what must be specified in the GFF file) and the specified units. For example if it is known that 5010 base pairs is equal to one Morgan, 5010 would be specified for the unit_divider. Note that if unit_divider is specified, max segment, default segment and and zoom levels will all be interpreted in terms of the specified units.
+:This turns on messages about general GBrowse operations.
-*'''max segment''', '''min segment'''
+;debug_external
-These options control the size of segments that will be shown in the detailed view.
+:This turns on messages concerning the uploading and processing of user-supplied tracks, as well as tracks fetched from remote sources via the [http://www.biodas.org DAS protocol].
-The max segment option sets an upper bound on the maximum size segment that will be displayed on the detailed view. Its value is in the selected units. Above this limit, the user will be prompted to select a smaller region on the birds-eye view. The default is 1,000,000 base pairs.
+;debug_plugins
+:This turns on debugging messages concerning the operation of GBrowse's user-contributed [[GBrowse Plugins | plugins]].
-If the user tries to view a segment smaller than the min segment option, then the segment will be resized to be this size. The default is 20 bp.
+====Configuring Genomic Regions====
+Several options allow you to configure the behaviour 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.
-*'''default segment'''
+{| class="wikitable"
-The default segment option sets the width of the segment (bp) that will be displayed when the user clicks on the birds-eye view without previously having set a desired magnification. You may want to adjust this value.
+ |-
+ ! option
+ ! default value
+ ! description
+ |-
+ | region segment
+ | 50000 (?)
+ | NOT DESCRIBED HERE PREVIOUSLY! DOES IT APPLY TO 2.0?? DESCRIBED ELSEWHERE (''If this configuration option is set, a new "region panel" will appear that is intermediate in size between the overview and the detail panel. The value of this option becomes the size of the region panel in base pairs.'')
+ |-
+ | max segment
+ | 5000000 (?)
+ | 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
+ | 100 500 1000 5000 50000 100000 (?)
+ | 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.
+ |-
+ | fine zoom
+ | 10%
+ | This option controls the increment that the user will zoom in or out when pressing the "+" and "-" buttons in the navigation bar.
+ |-
+ | default segment
+ | 5000 (?)
+ | 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
+ | 1000 5000 10000 20000 (?)
+ | This option is similar to '''zoom levels''' except that the list of zoom levels applies to the region panel.
+ |-
+ | default region
+ | 5000 (?)
+ | 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.
+|}
-*'''zoom levels'''
+====HTML Customization Settings====
-GBrowse allows unlimited zoom levels. This option selects the width of each level, in bp. For example:
-      zoom levels = 1000 2000 5000 10000 20000 40000 100000 200000
+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.
-*region segment
+;header, footer
-If this configuration option is set, a new "region panel" will appear that is intermediate in size between the overview and the detail panel. The value of this option becomes the size of the region panel in base pairs.
+<div class="indent">
+These two options place HTML at the top or bottom of the page. Example:
-*'''region sizes'''
+<pre>
-This contains a space-delimited list of region panel sizes to present to the user in a popup menu:
+ header = <img src="/banner.jpg">
+ footer = <hr>For help please see the <a href="help.html">help pages.</a>
+</pre>
+</div>
-     region sizes   = 5000 10000 20000
+;html1, html2, html3, html4, html5, html6
+<div class="indent">
+These options insert snippets of HTML in various strategic places on the page:
-*'''show sources'''
+{| class="wikitable"
-A 0 (false) or 1 (true) value which controls whether or not to show the popup menu displaying the defined data sources. Set this to 0 if you wish for the names of the data sources to be hidden. If not present, this option defaults to 1 (true).
+! 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
+|}
+</div>
+These can be used with callbacks to bring in local or external html files, e.g.
+<syntaxHighlight language=perl>
+header = sub{
+       open FILEHANDLE, 'somefile.txt' or die $!;
+       my $html_header = do { local $/; <FILEHANDLE> };
+       return $html_header;
+       }
+</syntaxHighlight>
+or
+<syntaxHighlight language=perl>
+header = sub{
+       use LWP::Simple;
+       my $html_header = get("http://example.org/header.html");
+       return $html_header;
+       }
+</syntaxHighlight>
-Note that all data sources will need to have this option defined in order for it to take effect across all databases.
+===Configured Data Source Sections===
-*'''default varying'''
+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:
-The track selection table will be sorted alphabetically, by default; setting this variable to true will cause the tracks to appear in the same order as they appear in the configuration file.
-*keyword search max
+ [''symbolic_name_of_data_source'']
-By default, gbrowse will limit the number of keyword search results to 1,000. The order in which the 1,000 hits are returned depends on how the database was loaded, and so you may see odd patterns, such as only hits on a particular chromosome being displayed. To raise the limit on keyword search results, set "keyword search max" to the desired maximum value.
+ description = ''human readable description of this data source''
+ path        = ''path_to_the_source_config_file''.conf''
-*overview units
+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.
-This option controls the units that will be used on the scale for the birds-eye view display. Possible values are "bp" (base pairs), "k" (kilobases), "M" (megabases), and "G" (gigabases). If this option is omitted, the browser will guess the most appropriate unit.
-*overview bgcolor
+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.
-This is the color for the background of the birds-eye view.
-*cache time
+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:
-The server will cache track images for a period of time in order to speed up performance. After the time has expired, the cached version of the image will not be used. This option specifies the time, in hours, that images will be cached. The default is 1 hour.
-If you are debugging your config file and want to see uncached images, call gbrowse with the CGI option nocache=1.
+<pre>
+default source = zebrafish v2
-*version
+[zebrafish v3]
-An optional numeric version for this configuration file. Every time gbrowse runs a user's request, it checks the value of the config file version against a version number saved in the user's settings. Of the current version is higher than the saved version, then gbrowse will reset the user's page session to its default values. Use this if you want to reset all users sessions to a known working state, or to draw their attention to a new feature you've added.
+description    = Zebrafish genome, build 2
+path           = zebra3.conf
-Example:
+[zebrafish v2]
+description    = Zebrafish genome, build 1 (deprecated)
+path           = zebra2.conf
+</pre>
-   version = 1.1
+If no '''default source''' option is defined, GBrowse will pick the first data source stanza as default.
-*detailed bgcolor
+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:
-This is the color for the background of the detailed view.
-*request timeout
+<pre>
-This is the timeout value for requests. If a user requests a large region and the request takes more than the indicated number of seconds, then the request will timeout and the user will be advised to choose a smaller region. The default is 60 seconds (one minute). You can make the timeout longer or shorter than this.
+[zebrafish v2]
+description    = Zebrafish genome, build 1 (deprecated)
+path           = zebra2.conf
+hide           = 1
+</pre>
-*head
+===Themes===
-This is content to insert into the HTML <head></head> section. It is the appropriate place to stick JavaScript code, etc. It can be a code reference if you wish.
-*header
+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:
-This is a header to print at the top of the browser page. It is any valid HTML, and can span multiple lines provided that the continuation lines begin with white space.
-It is also possible to place an anonymous Perl subroutine here. The code will be invoked during preparation of the page and must return a string value to use as the header. See COMPUTED OPTIONS for details.
+;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.
-Example:
+You can switch between themes by finding this GBrowse.conf line:
-    header = &lt;h1&gt;Welcome to the Volvox Sequence Page&lt;/h1&gt;
+ #include "themes/transparent_colors"
-*onload
+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.
-This is the name of javascript function(s) to be called via the page body's onload event handler. Any text included here will be used to mark-up the <body> element of the html printed by the gbrowse script. The onload event handler will fire *after* the page is finished loading, so this setting will be useful for running javascript functions that rely on all or part of the HTML having been loaded and interpreted by the browser. The onload text must use correct javascript syntax. For example:
-  onload = alert('I am about to do something');doSomething('arg1','arg2')
+==Data Source Configuration Files==
-will result in
+Each data source has a 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 [[#The GENERAL Section | [GENERAL] section]], the [[#Database Definitions | Database Definitions]] section, and the [[#Track Definitions | Track Sections]]. In addition there are some special sections that allow you to configure [[#Advanced Topics | Advanced Options]].
- <body onload="alert('I am about to do something');doSomething('arg1','arg2')">
+The following shows a basic data source configuration file:
-*footer
+<pre>
-This is a footer to print at the bottom of the browser page. It is any valid HTML, and can span multiple lines provided that the continuation lines begin with white space.
+[GENERAL]
+description   = Yeast chromosomes 1+2 (basic)
+database      = scaffolds
-It is also possible to place an anonymous Perl subroutine here. The code will be invoked during preparation of the page and must return a string value to use as the header. See COMPUTED OPTIONS for details.
+initial landmark = chrI:143000..180000
-Example:
+default tracks = Genes
+		   ORFs
+		   tRNAs
+		   CDS
+		   Transp
+		   Centro:overview
+		   GC:region
-    footer = <hr>
+# examples to show in the introduction
-        <table width="100%">
+examples = chrI
-        <TR>
+	   chrII
-        <TD align="LEFT" class="databody">
+	   chrI:80,000..120,000
-        For the source code for this browser, see the <a href="http://www.gmod.org">
+	   "membrane trafficking"
-        Generic Model Organism Database Project.</a>  For other questions, send
+	   NUT21
-        mail to <a href="mailto:lstein@cshl.org">lstein@cshl.org</a>.
+	   YAL063C
-        </TD>
-        </TR>
-        </table>
-*examples
+#################################
-You can provide GBrowse with some canned examples of "interesting regions" for the user to click on. The examples option, if present, provides a space-delimited list of interesting regions. For example:
+# database definitions
+#################################
-       examples = II  NPY1 NAB2 Orf:YGL123W
+[scaffolds:database]
+db_adaptor    = Bio::DB::SeqFeature::Store
+db_args       = -adaptor memory
+                -dir    $DATABASES/yeast_scaffolds
-*automatic classes
+[annotations:database]
-When the user types in a search string that is not qualified by a class (as in EST:yk1234.5), GBrowse will automatically search for a matching feature of class "Sequence". You can have it search for the name in other classes as well by defining the "automatic classes" option.
+db_adaptor    = Bio::DB::SeqFeature::Store
+db_args       = -adaptor memory
+                -dir    $DATABASES/yeast_chr1+2
-Example:
-        automatic classes = Symbol Gene Clone
+# Default glyph settings
+[TRACK DEFAULTS]
+glyph       = generic
+database    = annotations
+height      = 8
+bgcolor     = cyan
+fgcolor     = black
+label density = 25
+bump density  = 100
-When the user types in "hb3", the browser will search first for a Sequence feature of class hb3, followed in turn by matching features in Symbol, Gene and Clone. The search stops when the first match is found. Otherwise, the browser will proceed to a full text search of all the comment fields.
+### TRACK CONFIGURATION ####
+# the remainder of the sections configure individual tracks
-*search attributes (Bio::DB::SeqFeature::Store adaptor only)
+[Centro:overview]
-When the browser has searched the name and alias of features without success, it will do a whole database keyword search by calling the database's search_notes() method. By default this will search the text of all attributes, including such things as protein sequence. The Bio::DB::SeqFeature::Store database is a bit smarter about searching, and will only, by default, search attributes named "Note". You can expand the search by giving a list of attribute names to the "search attributes" option.
+feature       = centromere
+bgcolor       = blue
+glyph         = dot
+fgcolor       = black
+height        = 8
+point         = 1
+key           = Centromeres
-*remote sources
+[tRNA:overview]
-This option allows you to add remote annotation sources to the menu of such sources at the bottom of the main window. The format is:
+feature       = tRNA
+glyph         = generic
+bgcolor       = lightgray
+fgcolor       = black
+height        = 4
+stranded      = 1
+description   = 1
+key           = tRNAs
-       remote sources = "Menu Label 1" http://url1.host.com/etc/etc
+[GC:region]
-                       "Menu Label 2" http://url2.host.com/etc/etc
+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
-*instructions, search_instructions, navigation_instructions
+[Genes]
-You may override the default instructions (as defined in the language-specific configuration files in conf/lang) by setting these options. For example:
+feature      = gene
+glyph        = so_transcript
+bgcolor      = yellow
+height       = 6
+description  = 0
+key          = Named gene
-         instructions = "Type in the name of a contig or clone."
+[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.
-*no search
+[tRNAs]
-If you don't want the "Landmark or Region" textbox to appear, set this to true. The user will still be able to search the database by appending q=<search term> to the URL.
+feature       = tRNA
+glyph         = generic
+bgcolor       = lightgray
+fgcolor       = black
+height        = 4
+stranded      = 1
+description   = 1
+key           = tRNAs
+</pre>
-          no search = 1
+===The GENERAL Section===
-*no autosearch
+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:
-If this option is set to a true value, then the user's previous search will not be automatically re-executed the next time he visits gbrowse. Instead, the previous search will be pasted into the "Landmark or Region" box and the user will have to press "Search" to reexecute it.
-*category tables
+;'''database'''
-This option allows you to group the on/off checkboxes for set of tracks into a rectangular M x N table. It can be used to highlight the experimental design of a microarray or ChIP-on-Chip experiment.
+:This option sets the default database to use when searching and displaying features. See [[#Database Definitions|Database Definitions]] below.
-The format is:
+;'''default tracks''','''default features'''
+<div class="indent">
+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:
-  category tables = 'category name' 'columnlabel1 columnlabel2 columnlabel3' 'rowlabel1 rowlabel2 rowlabel3'
+  default tracks = Genes ORFs tRNAs CDS Centro:overview
-Where "category name" is the name of the track category (described in more detail below), "columnlabelN" is the label of the Nth column, and "rowlabelN" is the label of the Nth row. For example:
+An earlier (deprecated) name for this option was '''default features''' and this name is recognized for backward compatibility.
+</div>
+;'''examples'''
+<div class="indent">
+This option designates a list of searches that the user can click on to see sample regions. For example:
-  category tables = 'ArrayExpts' 'strain-A strain-B strain-C' 'temperature anaerobic aerobic'
+  examples = chrI
+	    chrII
+	    chrI:80,000..120,000
+	    "membrane trafficking"
+	    NUT21
+	    YAL063C
+</div>
+;initial landmark
+<div class="indent">
+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:
-This will set up all the tracks labeled with category "ArrayExpts" so that they are displayed in a 2x3 table like this:
+ initial landmark = chr1:50000..150000
+</div>
+;metadata
+<div class="indent">
+You can use this option to create machine- and human-readable information about your database. It is used to populate the information that appears when the user selects the "About this database" menu item. The full format is as follows:
-                 temperature     anaerobic      aerobic
+  metadata =
-   strain-A      track 1          track 4       track 7
+        -description             Example GBrowse database containing information from WormBase and modENCODE.
-   strain-B      track 2          track 5       track 8
+        -maintainer              Lincoln Stein <lincoln.stein@gmail.com>
-   strain-C      track 3          track 6       track 9
+        -created                 2010-1-4
+        -modified                2009-9-1
+        -authority               WS
+        -coordinates             http://www.dasregistry.org/coordsys/CS_DS109
+        -coordinates_version     170
+        -source                  Chromosome
+        -testrange               I:7385068..7387651
+        -species                 Caenorhabditis elegans
+        -taxid                   6239
-"track N" will be replaced with the name you selected for the track.
+All the fields are optional. '''-description''' provides a human-readable description of the database. '''-maintainer''' provides a name and contact address for users. '''-created''' and '''-modified''' give the date (in year-month-day format) when the database was created and modified. '''-species''' and '''-taxid''' provide the systematic species name and NCBI taxon ID for the species.
-Additional category tables can be specified using continuation lines:
+'''-authority''', '''-coordinates''', and '''-coordinates_version''' together provide information on the genome build used for this database. '''-authority''' is a prefix to be added to the coordinates_version that indicates the organization that performed the build. You can make one up, but it is better to consult a growing registry of these prefixes at http://www.dasregistry.org/help_coordsys.jsp; you can easily add a new one using the registry service. Registered coordinate systems receive a URL from the registry, which you can use for the '''-coordinates''' option.
- category tables = 'ArrayExpts' 'strain-A strain-B strain-C' 'temperature anaerobic aerobic'
+'''-source''' indicates the type of the coordinate system you are using, usually either "Chromosome" or "Contig."
-                   'CHiP-Chip'  'TFX1 ONE-CUT PHA4' '16-cell-stage 320-cell-stage adult'
-See the tutorial for more details.
+'''-testrange''' provides an example coordinate range that users can try out.
-*instructions section =item * search section =item * overview section =item * region section =item * details section =item * tracks section =item * display_settings section =item * upload_tracks section
+Should you wish to continue a long description across multiple lines, simply leave whitespace in front of the second and subsequent lines.
-These options control which sections are displayed and whether they are initially open or collapsed. Their values are one of:
+</div>
+;'''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.
- open     Show the section initially open
+;'''seqid_prefix'''
- closed   Show the section initially collapsed
+<div class="indent">
- off      Do not show the section at all
+It sometimes happens that different web databases disagree about how chromosomes are named. For example, in C. elegans, WormBase data dumps use chromosomes named "I", "II", etc, while the UCSC Genome Browser uses "chrI", "chrII", etc. This makes interoperation difficult via [[Galaxy]] and other workflow managers. If '''seqid_prefix''' is defined, then the prefix will be ''added'' to the chromosome names for all data dumps from the browser and ''stripped'' from all data uploads. For example, WormBase can specify:
-For example "instructions section = closed" will initially show the instructions section in collapsed form when the user visits gbrowse for the first time. "upload_tracks section = off" will disable the uploads section entirely.
+  seqid_prefix = chr
-Note that turning off the details section will effectively disable gbrowse, but you might want to do this if you want to show the overview section only. Turning off the search section will also disable the navigation buttons. If you want to disable searching selectively, you should use the "no search" option instead.
+to add "chr" to all its chromosome names on the way to [[Galaxy]]/UCSC and to strip "chr" from all chromosome names received from Galaxy/UCSC.
+</div>
-*html1, html2, html3, html4, html5, html6
+===Database Definitions===
-These options allow you to insert HTML into the GBrowse page at strategic places. Eventually this will be replaced with an HTML template system, but for now, this is the best we have.
- <table>
+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.
- <tr><th>Option</th><th>Where it goes</th></tr>
- <tr><td>header</td><td>between the top and the instructions</td></tr>
- <tr><td>html1 </td><td>between the instructions and the navigation bar</td></tr>
- <tr><td>html2 </td><td>between the navigation bar and the overview</td></tr>
- <tr><td>html3 </td><td>between the overview and the detail view</td></tr>
- <tr><td>html4 </td><td>between the detail view and the data source panel</td></tr>
- <tr><td>html5 </td><td>between the data source panel and the track list</td></tr>
- <tr><td>html6 </td><td>between the track list and the annotation upload</td></tr>
- <tr><td>footer</td><td>between the annotation upload and the bottom</td></tr>
- </table>
-These can be code references. One useful thing to do is to use the language translator to insert language-specific HTML. Here's an example provided by Marc Logghe:
+There are a variety of database backends that work with GBrowse 2; the major ones are [http://doc.bioperl.org/releases/bioperl-current/bioperl-live/Bio/DB/SeqFeature/Store.html Bio::DB::SeqFeature::Store], a database designed for rapid access to [http://www.sequenceontology.org/gff3.shtml GFF3-format] annotation data, Bio::DB::Das::Chado, an interface to the powerful [http://gmod.org/wiki/Chado_-_Getting_Started Chado database], {{CPAN|Bio::Das}}, an interface to the [http://www.biodas.org Distributed Annotation System], Bio::DB::Das::BioSQL, an interface to the [http://www.biosql.org/wiki/Main_Page BioSQL system], and lastly [http://www.bioperl.org/wiki/Module:Bio::DB::GFF Bio::DB::GFF], a quick and dirty interface to [http://www.sanger.ac.uk/Software/formats/GFF/GFF_Spec.shtml GFF2-formatted] annotation data. See [[GBrowse Backends]] for more information about these adaptors.
-    html2 = sub {
+A typical Bio::DB::SeqFeature::Store database configured to run directly from flat files is configured like this:
-        my $go = $main::CONFIG->tr('Go');
-        return
-        qq(
-        <table width="800" border="0">
-        <tr class="searchbody">
-        <td align="left" colspan="3" />
-        <b>Dump:</b><input type="button" value="Assembly" onclick="window.open('gbrowse?plugin=AssemblyDumper;plugin_action=$go');">
-        <input type="button" value="Reads" onclick="window.open('gbrowse?plugin=ReadDumper;plugin_action=$go');">
-        </td>
-        </tr>
-        </table>
-        );
-       }
-If you use a coderef for the html options, the subroutine is passed two arguments. The first argument is a Bio::Das::SegmentI object (see the manual page for Bio::DB::GFF::RelSegment for details). The second argument is a hashref containing the user's settings for the current page.
+ [scaffolds:database]
+ db_adaptor    = Bio::DB::SeqFeature::Store
+ db_args       = -adaptor memory
+                 -dir    /home/fred/gbrowse/databases/yeast_scaffolds
-*keystyle, empty_tracks
+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:
-These two general options control the appearance of the keys printed on the detailed view. keystyle takes one of two values "between" or "beneath".
-       keystyle = between
+ Bio::DB::SeqFeature::Store->new(-adaptor=> 'memory',
-       Print the track labels between the tracks themselves.
+                                 -dir    => '/home/fred/gbrowse/databases/yeast_scaffolds').
-       keystyle = beneath
+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''.
-       Print the track labels at the bottom of the detailed view.
-The "empty_tracks" option controls what to do when a track has no features in it. Possible values are:
+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:
-       empty_tracks = key
+ [GENERAL]
-       Print just the key (the track label).
+ database = scaffolds
-       empty_tracks = suppress
+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:
-       Suppress the track completely.
-       empty_tracks = line
+ [GENERAL]
-       Draw a solid line across the track.
+ db_adaptor    = Bio::DB::SeqFeature::Store
+ db_args       = -adaptor memory
+                 -dir    /home/fred/gbrowse/databases/yeast_scaffolds
-       empty_tracks = dashed
+'''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.
-       Draw a dashed line across the track.
-The default value is "key."
+====Database Search Options====
-*background, postgrid
+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:
-These two options can be used to place custom background images in the details panel and are useful for advanced operations such as colorizing the panel to show gaps in the assembly. Either option accepts either the path to a graphics file to be tiled onto the background, or a callback subroutine. In the case of the latter the callback will passed a two argument list consisting of the GD::Image object and the Bio::Graphics::Panel object. This gives the callback a chance to draw on top of the background using GD library calls.
-The only difference between the two options is the time that they are applied relative to the grid that shows base pair coordinates. The background option is invoked before the grid is drawn so that the grid appears on top of it. The postgrid option is invoked after the grid is drawn, so that anything the option draws appears on top of the grid. See http://sourceforge.net/mailarchive/message.php?msg_id=12116755 for an example of using this feature to show assembly gaps as vertical gray regions.
+ [scaffolds:database]
+ db_adaptor    = Bio::DB::SeqFeature::Store
+ db_args       = -adaptor memory
+                 -dir    /home/fred/gbrowse/databases/yeast_scaffolds
+ search options = exact, -fulltext, +autocomplete
-For a clever example of how to use postgrid calls, see the SynView synteny browser in the contrib directory of the GBrowse distribution. It uses a standard GBrowse configuration file with postgrid calls to draw trapezoids between glyphs to show synteny. For an example of how this looks, see http://www.plasmodb.org/cgi-bin/gbrowse/plasmodb/?start=101357;stop=121356;ref=MAL12;width=800;version=100;label=AnnotatedGenes-SyntenySpansVivaxMC-SyntenyGenesVivaxMC.
+ [expression:database]
+ db_adaptor    = Bio::DB::SeqFeature::Store
+ db_args       = -adaptor DBI::mysql
+                 -dsn yeast_expression_data
+ search options = none
-*image_padding = 25
+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.
-*pad_left = 50
-*pad_right = 30
-The image_padding option will add the indicated amount of whitespace (in pixels) to the right and left of the detail panel. The default is 25 pixels. You may need to adjust this if you are using the xyplot glyph and finding that the scale (which is printed outside the graph area) is being cut off.
-You can individually adjust the left and right padding using pad_left and pad_right, which, if present, will supersede image_padding.
+Turn all searches on, except for the full text search:
-*show track categories
+ search options = all -fulltext
-If this option is set to a true value, then tracks that have been assigned to categories (using the "category" option described later), will have their categories included in their labels. For example, a track of key "Protein matches" and category "vertebrate" will be displayed in a track labeled "Protein match (vertebrate)".
-The default is false.
+Add autocomplete to the default searches:
-*das mapmaster
+ search options = default +autocomplete
-This option, which should appear somewhere in the [GENERAL] section, indicates that the database should be made available as a DAS source. The value of the option corresponds to the URL of the DAS reference server for this data source, or "SELF" if this database is its own reference server. (See http://www.biodas.org/ for an explanation of what reference servers are.)
-Please see DAS_HOWTO for more information on using DAS with GBrowse.
+Only do exact searching:
-*proxy, http proxy, ftp proxy
+ search options = exact
-If your web server is behind a firewall and needs to use a proxy in order to access remote HTTP or FTP sites, then one or more of these options needs to be specified in order for the "add remote annotations" feature to work (both for file-based and DAS-based remote annotations). "http proxy" will set the proxy to use for outgoing HTTP connections, "ftp proxy" will set the proxy to use for outgoing FTP connections, and "proxy" will set both. The value is the URL of the proxy:
-   proxy = http://myproxy.myorg.com:9000
+The search types are:
-*session driver
+;all
-*session args
+:Enable all search types.
-These options fine-tune how gbrowse manages its state-maintaining sessions. GBrowse uses CGI::Session to store session data on the server. By default (if neither of these options is present), it uses CGI::Session's "file" driver and "default" serializer. The session files are stored in the "sessions" directory underneath the directory specified by the "tmpimages" option (e.g. /usr/local/apache/htdocs/gbrowse/tmpimages/sessions).
+;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!
+;heuristic
+: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.
-The "session driver" option will be passed to CGI::Session->new() as the first argument. It specifies the driver, serializer and ID generator according to the syntax described in the CGI::Session manual page. The "session args" option will be passed to CGI::Session->new() as the third argument. It specifies additional parameters to be passed to the selected driver.
+===Track Definitions===
-For example, here is how to create session data that is stored in the MySQL "test" database under a table named "gbrowse_sessions." The session data will be stored in binary form by the Storable module:
+To add tracks to a data source, you will create a series of one or more track definition stanzas. Alternatively, if you have the [[#Configuring_the_User_Account_Database|user account login]] system running, you can use the [[GBrowse 2.0 Install HOWTO/Advanced#The Admin Interface|admin interface]] to upload, configure and manage tracks remotely. This section describes the direct method of configuring tracks by directly editing the data source configuration file.
- session driver = driver:mysql;serializer:storable
+Following the database stanzas in the data source configuration file 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|semantic zooming]] (in which the appearance of the track changes at different magnification levels) and tracks generated by plugins.
- session args   = DataSource test
-                  TableName  gbrowse_sessions
-See the CGI::Session documentation for information about setting up the MySQL table and appropriate permissions.
+A typical track definition looks like this:
-You might also want to read about CGI::Session::ID::salted_md5 for an ID generation algorithm that should be more secure (but slightly slower) than the default one.
+ [Genes]
+ database     = annotations
+ feature      = gene
+ glyph        = generic
+ bgcolor      = yellow
+ height       = 6
+ link         = http://www.google.com/search?q=$name
+ key          = Named genes
-You will not ordinarily need to use these settings, as the defaults seem to work well. If you change these defaults, be sure to change them in '''all''' configuration files; otherwise weird stuff will happen when moving from one data source to another.
+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.
-*remember settings time
+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:
-The length of time to remember page-specific settings in the format "+NNNu", where NNN is a number and "u" is a unit ("w" = weeks, "d" = days, "M" = months). For example:
-  remember settings time = +3M   # remember settings for 3 months
+ [TRACK DEFAULTS]
+ glyph  = generic
+ height = 10
-The users' settings, which includes uploaded files, track options and plugin configuration, will be reset to the default if he or she fails to visit the site within the time specified.
+Individual tracks can override these defaults simply by changing the "glyph" and "height" options.
-The default value is 1 month.
+====Database and Rendering Backend Options====
-See the CGI manual page for more information on the time format.
+Several track options affect the connection between the gbrowser and the underlying database backend(s):
-*remember cookie time
+;database
-This is the length of time before the user's session cookie will stay on disk before it expires. It should be significantly longer than "remember settings time." The default is 12 months.
+: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.
-*remember source time
+;feature
-Deprecated. Use "remember cookie time" instead.
+<div class="indent">
+This relates the track to one or more feature types as they appear in the database. Recall that each feature has a '''type''' and a '''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 "type" 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.
-*msie hack
+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:
-GBrowse uses HTTP POST to transfer the current page settings to the web server. Because of the way that Microsoft Internet Explorer caches pages, when users of this browser press the "Back" button, MSIE will display an annoying alert that prompts the user to reload the page.
-When you set "msie hack" to a true value, Gbrowse will use the GET request when it detects MSIE in use. This will fix the "Back" button issue, but will put very long URLs in the Location box. It is your choice which of these is more annoying to your users.
+ feature = gene:sgd stRNA:sgd
-* suppress_menu
+This will include features of type "gene:sgd" and "stRNA:sgd" in the same track and display them in a similar fashion.
-This option will cause the browser to ignore your configuration file when building the source menu.  Your sourcse will still be accessible by URL using the gbrowse/yourSource or gbrowse?src=yourSource syntax.  One possible application for this feature would be to your data source while you are testing a new configuration.
+</div>
+;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.
-==The [TRACK DEFAULTS] section==
+;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.
-The track defaults section specifies default values for each track. The following common options are recognized:
+Example:
+ remote feature = http://www.wormbase.org/cgi-bin/das/wormbase?type=mRNA
-             glyph
+;remote renderer
-             height
+: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 | Running a GBrowse2 Render Farm ]] for information on using this option.
-             bgcolor
-             fgcolor
-             fontcolor
-             font2color
-             strand_arrow
-These options control the default graphical settings for any annotation types that are not explicitly specified. See the section below on controlling the settings. Any of the options allowed in the [track] sections described below are allowed here.
+;inline_imagemaps
+:This option is new in version 2.44. In previous versions, the imagemap data, which tells the browser what to do when the user hovers over a feature or clicks on it, was generated at the time the track is generated. However, this slows down track generation when there are many features, such as when showing next generation sequencing data. In version 2.44, the imagemaps are only generated as needed when the use clicks or hovers over a feature. The downside of this is that popup balloons are slightly delayed when GBrowse is running as a vanilla CGI application (there is no noticeable delay under FastCGI). Set '''inline_imagemaps''' to a true value to restore the original behavior. This can be done on a per-track basis or globally in [TRACK DEFAULTS].
-*label density
+;das category, das landmark, das flatten, das subparts, das superparts, das glyph, das type
-When there are too many annotations on the screen GBrowse automatically disables the printing of identifying labels next to the feature. "label density" controls where the cutoff occurs. The value in the example files is 25, meaning that labels will be turned off when there are more than 25 annotations of a particular type on display at once.
+:All these options pertain to exporting the GBrowse database as a DAS data source. Please see the [[GBrowse DAS HOWTO]] for more information.
-*bump density
+====Glyph and Appearance Options====
-When there are too many annotations on the screen GBrowse automatically disables collision control. The "bump density" option controls where the cutoff occurs. The value in the example files is 100, meaning that when there more than 100 annotations of the same type on the display, the browser will stop shifting them verticially to prevent them from colliding, but will instead allow them to overlap.
-*link
+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.
-The link option creates a default rule for creating 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:
+;bgcolor
+:This controls the background color of the glyph. The format of colors is explained in [[Glyphs and Glyph Options]].
-     $name        The feature's name (group name)
+;fgcolor
-     $id          The feature's id (eg, PK from a database)
+:This controls the foreground color (outline color) of the glyph. The format of colors is explained in  [[Glyphs and Glyph Options]].
-     $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:
+;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.
-     link = http://www.wormbase.org/db/get?name=$name;class=$class
+;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.
-At run time, if the user clicks on an EST named yk1234.5, this will generate the URL
+;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.
-     http://www.wormbase.org/db/get?name=yk1234.5;class=EST
+;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 [[Glyphs and Glyph Options]]. The "generic" glyph is the default.
-It is possible to override the global link rule on a feature-by-feature basis. See the next section for details on this. It is also possible to declare a subroutine to compute the proper URL dynamically. See COMPUTED OPTIONS for details.
+;height
+:This option sets the height of the glyph. It is expressed in pixels.
-A special link type of 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.
+;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.
-*link_target
+;strand_arrow
-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:
+: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.
-       link_target = _blank
+;feature_limit
+:This option will limit the number of features displayed in the track to a maximum. It can be useful in situations such as mRNA alignments where regions around highly-expressed genes contain orders of magnitude more features than typical regions. You may also place this option into [TRACK DEFAULTS] as a safety mechanism:
+<div class="indent">
+ [TRACK DEFAULTS]
+ feature_limit = 500
+</div>
+;visible
+:This option controls the default visibility of the track and is one of '''show''', '''hide''' or '''collapsed'''. If present, it overrides the general "default tracks" setting.
-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.
+;label density
+:This is a numeric option. When there are more features visible in the track than the indicated number, their labels will be turned off to save space. This can be overridden by the user.
-The "link_target" option can also be computed dynamically. See COMPUTED OPTIONS for details.
+;bump density
+:This is a numeric option. When there are more features than the number indicated, vertical collision control will be turned off; all features will be confined to a single horizontal line at the top of the track. This can be overridden by the user.
-*title
+;show summary
-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 COMPUTED OPTIONS for details.
+:This is a numeric option. When the region being displayed is larger than the indicated length (in base pairs), then the track will go into summary mode and show a density gram of the number of features in the track. This will greatly speed up the display of dense tracks over large regions and increases legibility. A value of zero disables summary mode. See [[#Summary_Mode_.28new_in_version_2.09.29 | Summary Mode]] for more information.
-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 &quot; entity, or the single quote ('). The function CGI::escapeHTML() is available to properly escape HTML characters in dynamically-generated titles.
+;bump
+:This option controls the packing of features. Possible values are:
+        no collision control
+        ordinary collision control; optimal tight packing applied to minimize wasted space
+        simple packing - each feature occupies separate vertical band
+ fast     faster packing which works best when all features are exactly same height
+ overlap  strand-specific collision control, and features are render translucent to allow the overlap to be seen
+: "overlap" bumping (version 2.46 and higher) is designed chiefly for quantitative (xyplot) tracks to show the overlap of quantitative peaks. It is usually combined with the "opacity" and "color_series" options.
+:The way strand-specific collision control works is that if two features are on the same strand, then they overlap with each other. If they are on different strands, then collision-control goes into effect. This gives you two horizontal bands, one for forward strand features, and one for negative strand features, and is a quick-and-dirty way to create composite features, such as coding genes and their regulatory elements.
-The special 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.
+;opacity (version 2.46 and higher)
+:This controls the opacity applied to features that collide using "bump=overlap". It is a floating point value between 0.0 and 1.0, where 0.0 is completely transparent, and 1.0 is entirely opaque. The default is 0.3.
-See CONFIGURE BALLOON TOOLTIPS for the ability to created rich tooltips including images and links.
+;color_series (version 2.46 and higher)
+:This option, if set to a true value, will cause GBrowse to assign background colors to features following a simple color series of (red blue green yellow orange brown aqua black fuchsia green lime maroon navy olive purple silver teal magenta). The color series is changeable using the '''color_cycle''' option. The option is usually used in conjunction quantitative tracks and "bump=overlap", so that superimposed xyplots are distinguishable on the basis of their color.
-*landmark_padding = 1000
+;color_cycle (version 2.46 or higher)
-The landmark_padding option will add the indicated number of base pairs to the right and left of all landmarks that are searched for by name.
+:This option, when used in conjunction with '''color_series''' sets the series of colors that features within the track will cycle among. It is a space-delimited set of Bio::Graphics-style colors.
+In addition, there are many glyph-specific options. Please see [[Glyphs and Glyph Options]] for details.
+====Track Table Options====
-==Track Sections==
+These options control the human-readable track label, as well as the way that tracks are grouped in the GBrowse tracks table.
-Any other [Section] in the configuration file is treated as a declaration of a track. The order of track sections will become the default order of tracks on the display (the user can change this later). Here is a typical track declaration from yeast.conf:
+;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.
- [Genes]
- feature      = gene:sgd
- glyph        = generic
- bgcolor      = yellow
- forwardcolor = yellow
- reversecolor = turquoise
- strand_arrow = 1
- height       = 6
- description  = 1
- key          = Named gene
-This track is named "Genes". You may use a short mnemonic if you prefer; this will make the URL shorter when the user bookmarks a view he or she likes. 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.
-Valid options are as follows:
-;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 method:source. So, for example, a feature of type "gene:sgd" has the method "gene" and the source "sgd".
-It is possible to omit the source. A feature of type "gene" will include all features whose methods are "gene", regardless of the source 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.
-;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
-;glyph
-:This controls the glyph (graphical icon) that is used to represent the feature. The list of glyphs and glyph-specific options are listed in the section GLYPHS AND GLYPH OPTIONS. The "generic" glyph is the default.
-;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.
-;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.
-;height
-:This option sets the height of the glyph. It is expressed in pixels.
-;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.
-;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.
-;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.
 ;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.
-;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.
-;link, title, link_target
-:These options are identical to the similarly-named options in the [GENERAL] section, but change the rules on a track-by-track basis. They can be used to override the global rules. To force a track not to contain any links, use a blank value.
-;box_subparts
-: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).
-;feature_low
-:If this option is present, GBrowse will use the list of feature types listed here at resolution views. (This is one of the ways that semantic zooming is implemented.) This allows you, for example, to switch off detailed exon, UTR, promoters and other within-the-gene features, and just show the start and stop of the transcription unit.
-;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.
-;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. See GROUPING FEATURES for details.
-;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
-(this feature is under refinement and may change in the future)
 ;restrict
-:This option allows you to restrict who is allowed to view the current track by host name, IP address or username/password. See AUTHENTICATION AND AUTHORIZATION for details.
+:This option allows you to restrict who is allowed to view the current track by host name, IP address or username/password. See [[GBrowse_Configuration/Authentication | 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:
+<div class="indent">
+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
-As of GBrowse version 1.7, it is possible to create subcategories using this syntax:
+You can also create nested categories by separating category names by colons:
+<pre>
    [label1]
    category = Genes:Coding
@@ Line 973: / Line 1,043: @@
    [label2]
    category = Genes:Non-coding
+</pre>
 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.
-Subcategories can be nested arbitrarily.
+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.
-If all tracks are categorized, then the "General" category will not be displayed.
+See the {{GBrowseAdminTutorialLink|GBrowse Tutorial}} for more details.
-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.
+</div>
-See the tutorial for more details.
+;subtrack select, subtrack table, subtrack labels (new in 2.10)
-;das category, das landmark, das flatten, das subparts, das superparts, das glyph, das type
+[[image:subtrack_selection_table.png|thumb|right|Subtrack selector]]
-:All these options pertain to exporting the GBrowse database as a DAS data source. Please see DAS_HOWTO for more information.
-A large number of glyph-specific options are also recognized. These are described in the next section.
+<div class="indent">
-==Glyphs and Glyph Options==
+These three options together allow you to create a series of named subtracks within a track. The user will be able to individually hide and show the subtracks, as well as to control their order using the user interface shown in the figure to the right. It is currently most useful for organizing a set of single features that span the entire chromosome, such as wiggle tracks.
-A large variety of glyphs are available, and more are being added as the Bio::Graphics module grows.
+See [[Creating_and_Managing_Subtracks_with_GBrowse2 | Creating Subtracks]] for a full description of subtrack creation and manipulation.
+</div>
-A list of the common glyphs and their options is provided by the GBrowse itself. Click on the "[Help]" link in the section labeled "Upload your own annotations". This page also lists the valid foreground and background colors. Most of the glyphs are found in the BioPerl distribution, but a few are distributed directly with GBrowse.
+;select (deprecated)
+<div class="indent">
+This is an older version of the subtrack creation mechanism, which is still supported for backward compatibility. See [[Creating_and_Managing_Subtracks_with_GBrowse2 | Creating Subtracks]] for the preferred way of doing this.
-The most popular glyph types are:
+The form of the "select" option is as follows:
-  Glyph                 Description
+ select = ''method'' ''value1'' ''value2'' ''value3'...
-  -----                 -----------
-  generic               a rectangle
+''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:
-  allele_tower          allele found at a SNP position
-  arrow                 an arrow
-  anchored_arrow        a span with vertical bases |-----|.  If one
-                        or the other end of the feature is off-screen, the
-                        base will be replaced by an arrow.
-  box                   another rectangle; doesn't show subparts of features
-  cds                   shows the reading frame of spliced transcripts; used
-                        in conjunction with the "coding" aggregator.
-  diamond               a point-like feature represented as a triangle
-  dna                   DNA and GC content
-  heterogeneous_segments a multi-segmented feature in which each segment can
-                        have a distinctive color.  For Jim Kent's WABA features,
-                        this works with the waba_alignment aggregator.
-  idiogram              this takes specially-formatted feature data and turns it
-                        into an idiogram of a Giemsa-stained metaphase chromosome
-  image                 this embeds photographic images and/or diagrams on features
-  processed_transcript  multi-purpose representation of a spliced mRNA, including
-                        positions of UTRs
-  segments              a multi-segmented feature such as an alignment
-  span                  like anchored_arrow, except that the ends are
-                        truncated at the edge of the panel, not turned
-                        into an arrow
-  trace                 reads an SCF trace file and draws a graphic representation
-  triangle              a point-like feature represented as a diamond
-  transcript            a gene model
-  transcript2           a slightly different representation of a gene model
-  translation           1-, 3- and 6-frame translations
-  wormbase_transcript   yet another gene model that can show UTR segments
-                        (for features that conform to the WormBase gene
-                        schema). Used in conjunction with the
-                        "wormbase_gene" aggregator.
-  xyplot                histograms and line plots
-A more definitive list of glyph options can be found in the Bio::Graphics manual pages. Consult the manual pages for the following modules:
+ select = source 'day 1' 'day 2' 'day 3'
-  Glyph                         Manual Page
+The matches are case insensitive regular expressions, so "day 1" will match "Day 1" and "DAY 1a".
-  -----                         -----------
+</div>
-  (common options for all)      Bio::Graphics::Glyph
+====Linking Options====
-  allele_tower                  Bio::Graphics::Glyph::allele_tower
-  arrow                         Bio::Graphics::Glyph::arrow
-  anchored_arrow                Bio::Graphics::Glyph::anchored_arrow
-  box                           Bio::Graphics::Glyph::box
-  cds                           Bio::Graphics::Glyph::cds
-  crossbox                      Bio::Graphics::Glyph::crossbox
-  diamond                       Bio::Graphics::Glyph::diamond
-  dna                           Bio::Graphics::Glyph::dna
-  dot                           Bio::Graphics::Glyph::dot
-  ellipse                       Bio::Graphics::Glyph::ellipse
-  extending_arrow               Bio::Graphics::Glyph::extending_arrow
-  generic                       Bio::Graphics::Glyph::generic
-  graded_segments               Bio::Graphics::Glyph::graded_segments
-  heterogeneous_segments        Bio::Graphics::Glyph::heterogeneous_segments
-  idiogram                      Bio::Graphics::Glyph::idiogram
-  image                         Bio::Graphics::Glyph::image
-  line                          Bio::Graphics::Glyph::line
-  primers                       Bio::Graphics::Glyph::primers
-  processed_transcript          Bio::Graphics::Glyph::processed_transcript
-  rndrect                       Bio::Graphics::Glyph::rndrect
-  ruler_arrow                   Bio::Graphics::Glyph::ruler_arrow
-  segments                      Bio::Graphics::Glyph::segments
-  span                          Bio::Graphics::Glyph::span
-  toomany                       Bio::Graphics::Glyph::toomany
-  trace                         Bio::Graphics::Glyph::trace
-  transcript                    Bio::Graphics::Glyph::transcript
-  transcript2                   Bio::Graphics::Glyph::transcript2
-  translation                   Bio::Graphics::Glyph::translation
-  triangle                      Bio::Graphics::Glyph::triangle
-  wormbase_transcript           Bio::Graphics::Glyph::wormbase_transcript
-  xyplot                        Bio::Graphics::Glyph::xyplot
-The "perldoc" command is handy for reading the documentation from the Unix command line. For example:
+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.
-   perldoc Bio::Graphics::Glyph::primers
+;balloon click, balloon hover
-This will provide you with a summary of the options that apply to the "primers" glyph.
+: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.
-In the manual pages, the glyph options are presented the way they are called from Perl. For example, the documentation will tell you to use the -connect_color option to set the color to use when drawing the line that connects the two inward pointing arrows in the primer pair glyph. This translates to the configuration file as an option named "connect_color". For example:
+;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).
- [PCR Products]
+;link
- glyph = primer
+<div class="indent">
- connect_color = blue
+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.
-When referring to colors, you can use a variety of color names such as "blue" and "green". To get the full list, cut and paste the following magic incantation into the command line:
+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:
-  perl -MBio::Graphics::Panel -e 'print join "\n",Bio::Graphics::Panel->color_names'
+{| class="wikitable"
+ ! Variable Name !! Value
+  |-
+ | $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
+ |}
-or see this URL:
+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.
+</div>
+;link_target
+<div class="indent">
+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 targeting 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|Computed Options]] for details.
+</div>
+;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 &quot; 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
+<div class="indent">
+For {{CPAN|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
+</div>
+====Subtrack Creation Options====
+Several options allow you to declare and configure subtracks, which are sets of filtered features organized within band inside the main tracks. These are described at length in [[Creating and Managing Subtracks with GBrowse2]].
+;metadata
+<div class="indent">
+If the track contains a small number of features that have distinct display names, such as a set of quantitative (wiggle) features, then use this option to associate an auxiliary "metadata" file with the features contained in this track. The metadata file describes each feature's distinguishing attributes and allows the user to select among them. See [[Creating and Managing Subtracks with GBrowse2]] for yhe file gormat and a worked example.
+</div>
+;subtrack select
+<div class="indent">
+If, on the other hand, the track contains a large number of features and it is impractical to enumerate them by hand, then use this option to define subtrack filters. Each filter becomes a heading in the subtrack selection dialog box, and combination of filters listed in the '''subtrack table''' option define each subtrack.
+Each filter declaration consists of two to three white-space separated values, terminated by a semicolon. The first value is the column label. The second column is a method call name to be applied to the feature (discussed at more length later). The optional third argument is an argument to be passed to the method call.
+The method name can be any of the methods accepted by Bio::SeqFeatureI feature objects. Typical methods used for the second argument are "display_name" (the name of the feature), "type", "method", "source", "score", "strand", "has_tag", and "tag_value". "has_tag" and "tag_value" both require the third argument to determine which tag to interrogate.
+Example:
+ subtrack select = Strand strand ;
+                   Status tag_value status
+This configuration will apply two filters to each feature to sort them into subtracks. The Strand filter will invoke each feature's strand() method, and the Status filter with call each feature's tag_value() method with an argument of "status", i.e. $feature->tag_value('status').
+</div>
+;subtrack table
+<div class="indent">
+This option defines the values that the dimensions can take on and specifies how to partition them into subtracks. Lines are separated by semicolons. Within each line are a series of values to be matched against the dimensions specified by "subtrack select" in the following format:
+ :subtrack_label matchval1 matchval2 matchval3... =id *
+The match values are required and must number the same as the dimension filters given in '''subtrack select'''. The optional '':subtrack label'' assigns a human-readable label to the subtrack for display purposes. The ":" character will not be displayed. ''=id'' assigns an ID to the subtrack for use when turning tracks on and off in the GBrowse URL. The "*" character, if present, will turn this subtrack on by default when the user loads the track for the very first time.
+When performing the match, values in this table that look like numbers will be compared using a numeric match. Otherwise they will be compared using a case sensitive exact string match. Values that are proceeded by the ~ symbol (e.g. "~abc") will be matched using a case-insensitive regular expression match.
+Example:
+ subtrack table = :"+Strand Curated"    +1 confirmed =fc * ;
+                  :"-Strand Curated"    -1 confirmed =rc * ;
+                  :"+Strand Predicted"  +1 predicted =fp   ;
+                  :"-Strand Predicted"  -1 predicted =rp
+The subtrack table option can also be used to highlight one type of feature in a larger collection and assign all others to a separate sub track.   The example below filters features by their source tag.  All features with a source other than "SpecialSource" will be assigned to the "Other" sub-track.
+ subtrack select = Source source
+ subtrack table  = :SpecialLabel SpecialSource;
+                   :Other 0;
+</div>
+;'''brief comment'''
+:This optional option is a bit of explanatory text to insert at the top of the subtrack selection dialog.
+;'''subtrack labels'''
+<div class="indent">
+If you would like to select subtracks based on its type, a tag, or some other method, but you want the user to see a different label for the value when it is displayed in the subtrack selection dialog, you can specify the label here. For example, if you wish the +1 and -1 values in the example above to be displayed using the terms "Forward" and "Reverse", you would define that this way.
+ subtrack labels = +1 "Forward" ;
+                   -1 "Reverse"
+</div>
-  http://www.wormbase.org/db/seq/gbrowse?help=annotation
+;hide empty subtracks
+:If this option is set to a true value, then subtracks that do not contain any data in currently viewed region will be suppressed. Otherwise, their titles will be printed and they will take up a small amount of blank vertical real estate.
-Alternatively, you can use the #RRGGBB notation to specify the red, green and blue components of the color. Refer to any book on HTML for the details on using the notation.
+See [[Creating and Managing Subtracks with GBrowse2]] for more information.
-==Adding features to the overview==
+===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":
@@ Line 1,117: / Line 1,254: @@
   key           = SNP Density
+===Semantic Zooming===
-==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(This section has been edited - "feature" line has been removed from the remaining stanzas):
-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:
+<pre>
    [gene]
    feature = transcript:curated
@@ Line 1,130: / Line 1,267: @@
    [gene:500]
-  feature = transcript:curated
+   glyph   = gene
-   glyph   = transcript2
    [gene:100000]
-  feature = transcript:curated
    glyph   = arrow
    [gene:500000]
-  feature = transcript:curated
    glyph   = generic
+</pre>
-This series of stanzas says to use the "transcript2" 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.
+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:
@@ Line 1,157: / Line 1,292: @@
    hide = 1
+===Summary Mode (new in version 2.09)===
-==Computed Options==
+[[Image:gbrowse_normal_mode.png|thumb|right|300px|Normal mode: each feature is rendered separately]]
+[[Image:gbrowse_summary_mode.png|thumb|right|300px|Summary mode: a density plot shows the number of features per interval]]
-Some options can be computed at run time by using Perl subroutines as their values. These are known as "callbacks." Currently this works with the values of the "link", "title", "link_target", "header" and "footer" options, and any glyph-specific option that appears in a track section.
+Summary Mode, which was introduced in version 2.09, is a form of semantic zooming in which the regular display of individual features is replaced by a density graph or histogram showing the number of features  across the displayed region. Because the rendering is very fast, users can zoom out to view the entire chromosome without waiting for a long redisplay. The two figures to the right show how a track appears in regular and summary mode.
-You need to know the Perl programming language to take advantage of this. The general format of this type of option is:
+There are certain limitations on summary mode:
-   option name = sub {
+#It only works with {{CPAN|Bio::DB::SeqFeature::Store}} databases, although support for the [[Chado]] and {{CPAN|Bio::DB::GFF}} [[GBrowse Adaptors|adaptors]] is pending. It does work with all flavors of Bio::DB::SeqFeature::Store, including the in-memory and Berkeleydb implementations.
+#You will need [[BioPerl]] version 1.6.2 or higher. The currently released version of BioPerl is 1.6.1, so you will need to get a newer version from the BioPerl source code repository (see below).
+#Bio::DB::SeqFeature::Store databases created with older versions of BioPerl will need to be upgraded to support summary mode. This is done easily and quickly with a command-line utility described below. The databases created by newer versions of BioPerl support summary mode automatically.
+Step-by-step instructions:
+====Install the development version of BioPerl====
+Download the latest "snapshot" of BioPerl from [http://www.bioperl.org/wiki/Getting_BioPerl The BioPerl Web Site]. Alternatively, you may use the "git" source code control command to make a local copy of the developers' repository. This will enable you to update BioPerl regularly. See [[http://www.bioperl.org/wiki/Using_Git#Instructions_for_downloading_any_BioPerl_repository_via_Github_.28read-only.29|Instructions for downloading BioPerl via Github]]. Follow the directions to run "perl Build.PL; Build; Build install".
+====Upgrade preexisting Bio::DB::SeqFeature::Store databases====
+You will need to upgrade your preexisting databases to take advantage of summary mode. This is done using the bp_seqfeature_load.pl script with the '''--summary''' command line option. Make sure you are using the '''new''' version of the script that comes with the developer's release of BioPerl.
+For a MySQL database named "my_genome" located on the localhost:
+   bp_seqfeature_load.pl -a DBI::mysql -d my_genome --summary
+The same, but with a username and password:
+  bp_seqfeature_load.pl -a DBI::mysql -d my_genome -u myname -p secret --summary
+The same, but on a remote host named "beehive":
+  bp_seqfeature_load.pl -a DBI::mysql -d my_genome:host=beehive -u myname -p secret --summary
+A SQLite database located at /usr/local/share/my_genome.sqlite:
+  bp_seqfeature_load.pl -a DBI::SQLite -d /usr/local/share/my_genome.sqlite --summary
+A Berkeleydb database located at /usr/local/share/my_genome.berkeley:
+  bp_seqfeature_load.pl -a berkeleydb -d /usr/local/share/my_genome.berkeley --summary
+In-memory databases do '''not''' need to be upgraded, nor do new databases created by bp_seqfeature_load.pl with the --create option.
+====Enable summary mode in your datasource configuration file(s)====
+Insert the '''show summary''' option within the [TRACK DEFAULTS] stanza:
+ [TRACK DEFAULTS]
+  ...
+  show summary = 1000000
+The value of "show summary" specifies the region length, in base pairs, at which to switch into summary mode. The example above specifies to switch into summary mode at a level of 1 Mb or higher (1,000,000 bp), but the appropriate value will be depend on the genome size and average number of features per chromosome.
+You may change this value on a track-by-track basis by adding "show summary" options to the track stanzas you wish to override. To turn summary mode off completely for a track, either set the value to something ridiculously high, or specify a value of "0".
+===Creating Subtracks (new in version 2.09)===
+[[image:subtrack_selection_table_overview.png|300px|right|Subtrack selector]]
+You can create an unlimited number of subtracks within a single major track in order to group a series of datasets that are logically linked, such as a timecourse. You can choose which subtracks to show by default and the order in which they will appear. The user can use a dialog box to select which subtracks to make visible and to reorder the subtracks.
+See [[Creating and Managing Subtracks with GBrowse2]] for full details.
+=Advanced Datasource Configuration Topics=
+This section describes how to further customize your GBrowse data sources to provide for an exceptional end-user experience.
+==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:
+<syntaxhighlight lang="perl">  option name = sub {
                some perl code;
                some more perl code;
                even more perl code;
-               }
+               }</syntaxhighlight>
 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.
@@ Line 1,174: / Line 1,376: @@
 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" and "header", the subroutine is passed no arguments. It is expected to produce some HTML and return it as a string value.
+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:
+<syntaxhighlight lang="perl">  bgcolor = sub {
-  bgcolor = sub {
            my $feature = shift;
            return "blue" if $feature->primary_tag eq 'exon';
            return "orange";
-           }
+           }</syntaxhighlight>
-See the manual page for Bio::DB::GFF::Feature for information on how to interrogate the feature object.
+See the manual page for {{CPAN|Bio::Graphics::Feature}} and {{CPAN|Bio::SeqFeature::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 {
+<syntaxhighlight lang="perl">   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';
-          }
+          }</syntaxhighlight>
 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 {
+<syntaxhighlight lang="perl">  sub {
           my($feature,$option_name,$part_no,$total_parts,$glyph) = @_;
           my $parent = $glyph->parent_feature;
           return 'blue' if $parent->name =~ /Blue\d+/;
           return 'red';
-          }
+          }</syntaxhighlight>
 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.
@@ Line 1,210: / Line 1,411: @@
 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 {
+<syntaxhighlight lang="perl">  link = sub {
               my ($feature, $panel, $track) = @_;
               ... do something
-              }
+              }</syntaxhighlight>
 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 {
+<syntaxhighlight lang="perl">  title = sub {
            my ($feature,$panel,$track) = @_;
            my $name = $feature->display_name;
            return $panel->flip ? "$name (flipped)" : $name;
-        }
+        }</syntaxhighlight>
 ===Named Subroutine References===
@@ Line 1,227: / Line 1,428: @@
 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 {
+<syntaxhighlight lang="perl">  init_code = sub score_color {
                  my $feature = shift;
                  if ($feature->score > 50) {
@@ Line 1,242: / Line 1,443: @@
                    return 5;
                  }
-               }
+               }</syntaxhighlight>
 Then simply refer to these subroutines using the \&name syntax:
@@ Line 1,253: / Line 1,454: @@
 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';
+<syntaxhighlight lang="perl">    init_code = no strict 'vars';
                  $HEIGHT = 10;
                  sub score_height {
@@ Line 1,263: / Line 1,464: @@
                      return $HEIGHT;
                    }
-                 }
+                 }</syntaxhighlight>
 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.
@@ Line 1,269: / Line 1,470: @@
 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:
+<pre>
     init_code = package My; sub score_height { .... }
     [EST_ALIGNMENTS]
     height = \&My::score_height
+</pre>
-==Declaring New Aggregators==
+===Using Pipes in the GBrowse.conf Data Source Name===
-The Bio::DB::GFF data model recognizes a single-level of "grouping" of features, but doesn't specify how to use the group information to correctly assemble the various individual components into a biological object. Aggregators are used to assemble this information. For example, let's say that you decide that your preferred "transcript" data model contains three subfeature types: a set of one or more features of method "exon", a single feature of method "TSS", and a single feature of method "polyA". Optionally, the data model could contain a single "main subfeature" that runs the length of the entire transcript. We might give this feature a method of "primary_transc" (for "primary transcript.")
-In a GFF file, a three-exon transcript might be represented as follows:
- Chr1 confirmed primary_transc 100 500  .  +  .  Transcript "ABC.1"
- Chr1 confirmed TSS            100 100  .  +  .  Transcript "ABC.1"
- Chr1 confirmed exon           100 200  .  +  .  Transcript "ABC.1"
- Chr1 confirmed exon           250 300  .  +  .  Transcript "ABC.1"
- Chr1 confirmed exon           400 500  .  +  .  Transcript "ABC.1"
- Chr1 confirmed polyA          500 500  .  +  .  Transcript "ABC.1"
-To aggregate this, you would like to create an aggregator named "transcript", whose "main method" is "primary_transc", and whose "sub methods" are "TSS," "exon," and "polyA."
-The way to indicate this in the configuration file is to add a "complex aggregator" to the list of aggregators:
-  aggregators = transcript{TSS,exon,polyA/primary_transc}
-The format of this value is "aggregator_name{submethod1,submethod2,.../mainmethod}".
-You can now use the name of the aggregator name as the argument of the "feature" option in a track section:
-  [Transcripts]
-  feature      = transcript
-  glyph        = segments
-  bgcolor      = wheat
-  fgcolor      = black
-  height       = 10
-  key          = Transcripts
-If you do not have a main subfeature, leave off the "/mainmethod". For example:
-  aggregators = transcript{TSS,exon,polyA}
-A few formatting notes. You are free to mix simple and complex aggregators in the "aggregator" option. For example, you can activate the standard "clone" and "alignment" aggregators as well as the new transcript aggregator with a line like this one:
- aggregators = clone
-               transcript{TSS,exon,polyA/primary_transc}
-               alignment
-If the complex aggregator contains whitespace or apostrophes, you must surround it with double-quotes, like this:
-   "transcript{TSS,5'UTR,3'UTR,exon,polyA/primary_transc}"
-Be aware that some glyphs look for particular method names when rendering aggregated features. For example, the standard "transcript" glyph is closely tied to the "transcript" aggregator, and looks for submethods named "intron", "exon" and "CDS", and a main method named "transcript."
-Here is the list of available predefined aggregators:
-     alignment
-     clone
-     coding
-     transcript
-     none
-     orf
-     waba_alignment
-     wormbase_gene
-To view the documentation for any of these aggregators, run the command "perldoc Bio::DB::GFF::Aggregator::aggregator_name", where "aggregator_name" is the name of the aggregator.
-==Grouping Features==
+It is sometimes convenient to generate datasource files programatically rather than using a static file. To do this, you can give GBrowse.conf a "path" option that uses Perl's "piped open" syntax to read the output of a script. For example:
-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.
+  # this is in GBrowse.conf
+  [modENCODE_preview]
+  description = modENCODE preview database
+  path        = /usr/local/modencode/bin/preview.pl |
-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:
+The script (preview.pl in this example) must print a correctly formatted GBrowse datasource configuration file to its standard output.
-      group_pattern =  /\.[53]$/
+[''Available in 2.09 and higher''] To get even more elaborate than this, you can use a regular expression as the stanza datasource name, allowing you to pass extracted subexpressions to the script. For example:
-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".
+ [=~modENCODE_preview_v(\d+)]
+  description = modENCODE preview database
+  path        = /usr/local/modencode/bin/preview.pl $1 |
-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:
+The "=~" prefix is required to turn on regular expression scanning. This will match any data source of the format "modENCODE_preview_v123" where "123" is a series of digits. The digits will be extracted using the regular expression and passed to preview.pl as an argument:
-      group_pattern = /\.(for|rev)\./
+ /usr/local/modencode/bin/preview.pl 123 |
-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.
+You can then invoke GBrowse with any of the following URLs and have the indicated script return the appropriate data source configuration data on its standard output:
+ http: //your.host/gb2/gbrowse/modENCODE_preview_v1
+ http: //your.host/gb2/gbrowse/modENCODE_preview_v2
+ http: //your.host/gb2/gbrowse/modENCODE_preview_v42
 ==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.
+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:
@@ Line 1,398: / Line 1,551: @@
 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 GFF line:
+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
@@ Line 1,423: / Line 1,576: @@
        }
+==Restricting Access to Data Sources and Tracks with Usernames and Passwords==
+See: [[GBrowse Configuration/Authentication]]
 ==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.
+See: [[GBrowse Configuration/Balloons]].
-In the config file for the database you wish to modify, set "balloon tips" to a true value:
+==Generating Static Images: PNGs, SVGs and PDFs==
-      [GENERAL]
+See: [[GBrowse Configuration/Images]].
-      ...
-      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.
+==Describing a GBrowse data source using structured meta-data==
-"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:
+If you wish, you can enter options into the datasource config file that will described the data in a structured way. This in turn can be used by automated scripts to discover the species, genomic build, the name of the maintainer, and other descriptive information about the data source. The information is compatible with the [http://www.dasregistry.org/ DAS Registration server] and in a coming GBrowse release will allow GBrowse instances to automatically register themselves so that users and automated scripts can easily find and extract information from the browser.
-  balloon hover = &lt;h2&gt;Gene $name&lt;/h2&gt;
+To enter metadata about a particular data source, go to the [GENERAL] section of its configuration file and enter a '''metadata''' option formatted like this one:
-  balloon click = &lt;h2&gt;Gene $name&lt;/h2&gt;
-                  &lt;a href='http://www.google.com/search?q=$name'&gt;Search Google&lt;/a&gt;&lt;br&gt;
-                  &lt;a href='http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=pubmed&term=$name'&gt;Search NCBI&lt;/a&gt;&lt;br&gt;
-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:
+<pre>
+ metadata =
+        -description             Example GBrowse database containing information from WormBase
+				 (www.wormbase.org) and modENCODE (www.modencode.org).
+        -maintainer              Lincoln Stein <lincoln.stein@gmail.com>
+        -created                 2010-1-4
+        -modified                2009-9-1
+        -authority               WS
+        -coordinates_version     180
+        -coordinates             http://www.dasregistry.org/coordsys/CS_DS109
+        -source                  Chromosome
+        -testrange               I:7385068..7387651
+        -species                 Caenorhabditis elegans
+        -taxid                   6239
+</pre>
-  balloon click = /cgi-bin/get_gene_data?gene=$name
+The '''metadata''' option has multiple suboptions (note the required leading whitespace in front of them):
-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:
+;'''-description'''
+:A free text description of the data source. It can span multiple lines.
+;'''-maintainer'''
+:An email address for the person or mailing list to contact concerning issues with the data source.
+;'''-created''','''-modified'''
+:The creation and modification date of the resource, in the format YYYY-MM-DD.
+;'''-authority''','''-coordinates_version''' and '''-coordinates'''
+:These fields establish the genome build and build version. The authority is a short prefix indicating the organization that is responsible for the build, such as "NCBI" (human), "WS" (WormBase), or SGD (Yeast), and coordinates_version indicates the version of the build. In the example above, therefore, the build is described as WS180. For greatest power, you can use '''-coordinates''' to provide a DAS registry coordinate system URL so that software that uses the DAS system can reliably combine tracks from different data sources. Many coordinate systems are already registered [http://www.dasregistry.org/help_coordsys.jsp at the DAS registry]; you may register a new one if needed.
+;'''-source'''
+:This describes the type of coordinate system used, either "Chromosome" or "Contig".
+;'''-testrange'''
+:This provides an example range for new users to look at.
+;'''-species''','''-taxid'''
+:These indicate the species name (in long binomial format) and the [http://www.ncbi.nlm.nih.gov/Taxonomy/ NCBI taxon id].
-  balloon click = url:/cgi-bin/get_gene_data?gene=$name
+Note that the support for automatic registration and discovery of GBrowse data sources is not available in the 2.00 release, but is expected to be added in a subsequent point release.
-This also allows you to refer to relative URLs:
+=Advanced Configuration Topics=
-  balloon click = url:../../get_gene_data?gene=$name
+==Maintaining the User Accounts Database==
-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:
+If you have the requisite modules installed (DBI, DBD::SQLite or DBD::mysql), then '''./Build install''' will run a script called "gbrowse_metadb_config.pl", which creates and initializes a user account database for managing user logins and shared tracks. If you take advantage of the user accounts feature (described in more detail in [[GBrowse_Configuration/Authentication]]), you may wish to run gbrowse_metadb_config.pl periodically. It checks for database inconsistencies, removes unused uploads, and does other routine maintenance on the user accounts database.
-* PNG -- a bitmapped format suitable for low-resolution graphics, such as web pages.
+==Removing Unused Sessions, Uploads and Cached Images==
-* 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 [http://www.wormbase.org/db/seq/gbrowse_img here].
+Over time GBrowse will accumulate unused sessions left by users who visit once and never return. Eventually these unused sessions will use up disk space and may adversely affect performance. The same issue affects custom tracks (uploaded files) and cached images.
-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 [http://www.cpan.org CPAN].
+You can clean up these files using the Unix "find" command:
-For PDF generation, you will need the perl GD and GD::SVG modules installed, as well as a helper application called [http://www.inkscape.org/index.php 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:
+     cd /var/tmp/gbrowse2
+     sudo -u www-data find . -type f -atime +20 -print -exec rm {} \;
- sudo mkdir ~www-data/{.inkscape,.gnome2}
+This will remove all files that have not been accessed for more than 20 days. Note that the command should run as the Apache web user ("www-data" in this example). The number of days is specified with '''-atime +20'''. Change 20 to some other value if you desire.
- 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.
+You may wish to run this as a daily cron job, either by adding it to the web user's cron table, or by running it in root's cron table.
-Unfortunately, Inkscape will generate a one line warning into the server error log every time it executes:
+==Other Advanced Topics==
- (inkscape:28490): Gdk-CRITICAL **: gdk_display_list_devices: assertion `GDK_IS_DISPLAY (display)' failed
+More installation and maintenance tips, including support for next generation sequencing data, user accounts, and more, are given in [[GBrowse 2.0 Install HOWTO#Advanced Installation Topics]]
-At the current time there is no known fix for this problem.
+=The GBrowse2 REST API=
-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.
+See: [[GBrowse2 REST API]] (section under construction)
-[[Category:Biologist]]
 [[Category:GBrowse]]
+[[Category:HOWTO]]
 [[Category:GMOD Components]]
+[[Category:GBrowse 2]]
+[[Category:Configuration]]

Difference between revisions of "GBrowse 2.0 HOWTO"

Latest revision as of 04:44, 9 January 2014

Contents

GBrowse Installation

GBrowse Virtual Machines

Ubuntu 11.10 and higher Binary Installs

Debian "sid" Binary Installs

Debian "wheezy" Binary Installs

Installation on Older Ubuntu and Debian Systems

Installation on RedHat, CentOS and other RPM Systems

Installation on MacOSX Systems

Installation from Source Code

Users of GBrowse 1.X

Configuring GBrowse

GBrowse.conf

The GBrowse.conf [GENERAL] Section

Paths and Directories

Session Settings

Performance Settings

Appearance Settings

Fast Track Panning (new in version 2.20)

Cleanup Settings

Upload Database Settings

Debug Settings

Configuring Genomic Regions

HTML Customization Settings

Configured Data Source Sections

Themes

Data Source Configuration Files

The GENERAL Section

Database Definitions

Database Search Options

Track Definitions

Database and Rendering Backend Options

Glyph and Appearance Options

Track Table Options

Linking Options

Grouping Options

Subtrack Creation Options

Adding Tracks to the Overview and Region Panels

Semantic Zooming

Summary Mode (new in version 2.09)

Install the development version of BioPerl

Upgrade preexisting Bio::DB::SeqFeature::Store databases

Enable summary mode in your datasource configuration file(s)

Creating Subtracks (new in version 2.09)

Advanced Datasource Configuration Topics

Computed Options

Named Subroutine References

Using Pipes in the GBrowse.conf Data Source Name

Controlling the gbrowse_details page

Linking out from gbrowse_details

Restricting Access to Data Sources and Tracks with Usernames and Passwords

Configuring Balloon Tooltips

Generating Static Images: PNGs, SVGs and PDFs

Describing a GBrowse data source using structured meta-data

Advanced Configuration Topics

Maintaining the User Accounts Database

Removing Unused Sessions, Uploads and Cached Images

Other Advanced Topics

The GBrowse2 REST API

Navigation menu

Search