GBrowse

 view release on metacpan or  search on metacpan

docs/pod/CONFIGURE_HOWTO.pod  view on Meta::CPAN

browser.  Just construct a URL that uses "sourcename" as a virtual
directory under cgi-bin/gbrowse:

  http://your.site.org/cgi-bin/gbrowse/sourcename/

(Note: If you don't add the slash at the end, gbrowse will
automatically do it for you, since the terminal slash is needed to
work around an apparent bug in MSIE's cookie handling.)

It is suggested that you use the same name as the database, although
this isn't a requirement.  (If no "source=" argument is given, gbrowse
picks the first configuration file that occurs alphabetically; you can
control this by placing numbers in front of the configuration file, as
in "01.yeast.conf".)

The configuration file is divided into a number of sections, each one
introduced by a [SECTION TITLE].  The [GENERAL] section contains
settings that are applicable to the entire application.  Other
sections define tracks to display.

I suggest that you begin with one of the example configuration files
provided with the distribution and modify it to suit your needs.

=head2 B1. The [GENERAL] Section

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:

 [GENERAL]
 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:

 description = S. cerevisiae annotations via SGD Nov 2001, and
	     converted using the process_sgd.pl script

Any lines that begin with a pound sign (#) are considered comments and
ignored.

During this discussion, you might want to follow along with one of the
example configuration files.

The following [GENERAL] options are recognized:

=over

=item * description

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

=item * db_adaptor

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.

=item * db_args

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:

    db_args = -adaptor dbi::mysql
              -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".

If the database requires you to log in with a user name and
password, use the following db_adaptor:

    db_args = -adaptor dbi::mysql
              -dsn     dbi:mysql:database=<db_name>;host=<db_host>
              -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.

To use the Oracle version of Bio::DB::GFF, use these arguments:

    db_args = -adaptor dbi::oracle
              -dsn dbi:oracle:database=db_service

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.

To use the in-memory version of Bio::DB::GFF, use these arguments:

  db_args = -adaptor memory
            -dir   /path/to/directory

The indicated directory should contain one or more GFF and FASTA files,
distinguished by the filename extensions .gff and .fa respectively.

=item * aggregators

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

To disable the default aggregators, leave this setting blank, as in:

     aggregators=

To activate the default aggregators of "transcript," "clone,"
and "alignment," comment this setting out entirely:

    # aggregators =

=item * user

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.

=item * pass

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.

=item * stylesheet

Location of the stylesheet used to create the GBrowse look and feel.
(You probably will not need to change this.)

=item * plugins

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

A good standard list of plugins is:

    plugins = SequenceDumper FastaDumper RestrictionAnnotator

See the contents of conf/plugins and contrib/plugins for more plugins
that you can install.

=item * quicklink plugins

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.

=item * plugin_path

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.

=item * buttons

URL in which the various graphical buttons used by GBrowse are located.
(You will probably not need to change this.)

=item * js

URL in which the gbrowse javascript helper function files are located.
(You will probably not need to change this).

=item * tmpimages

URL of a writable directory in which GBrowse can write its temporary
images. The format is:

  tmpimages = <tmpimages_url> <tmpimages_path>

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.

The tmpimages option is mandatory.

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.

=item * cachedir

This is a writable directory that can be used for caching
gbrowse_img-generated images. Defining it will speed up some
operations. If not defined gbrowse_img will still work, but will
regenerate images from scratch even if they've been used before. It is
OK to use the same path as the tmpimages directory.

=item * image widths

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.

=item * default width

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.

=item * default features

docs/pod/CONFIGURE_HOWTO.pod  view on Meta::CPAN

=item * truecolor

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.

=item * units, unit_divider

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.

=item * max segment, min segment

These options control the size of segments that will be shown in the
detailed view.

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.

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.

=item * default segment

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.

=item * zoom levels

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

=item * region segment

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 initial size of the region
panel in base pairs.

     region segment = 10000

=item * region sizes

This contains a space-delimited list of region panel sizes to present
to the user in a popup menu:

     region sizes   = 5000 10000 20000

=item * show sources

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

Note that all data sources will need to have this option defined in
order for it to take effect across all databases.

=item * default varying

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.

=item * keyword search max

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.

=item * overview units

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.


=item * overview bgcolor

This is the color for the background of the birds-eye view.

=item * selection rectangle color

This is the color of the rectangle in the overview and region
panels that shows where on the overview the detail panel represents.
The default is red.

=item * cache_overview

This option will cause the overview images to be cached on disk for a
period of time.  This may improve performance if you are placing many
complex tracks into the overview.  The value is the number of hours to
keep the cached copy of the overview image before refreshing it
(default = don't cache).

You can freshen the cache and force cached copies to be ignored by
touching the configuration file or by calling gbrowse with the CGI
option nocache=1.

=item * detailed bgcolor

This is the color for the background of the detailed view.

=item * request timeout

This is the timeout value for requests.  If a user requests a large
region and the request takes more than the indicated number of

docs/pod/CONFIGURE_HOWTO.pod  view on Meta::CPAN

     $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

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.

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.

=item * link_target

By default links will replace the contents of the current window.
If you wish, you can specify a new window to pop up when the user
clicks on a feature, or designate a named window or frame to
receive the contents of the link.  To do this, add the "link_target"
option to the [TRACK DEFAULTS] section or to a track stanza.  The format
is this:

       link_target = _blank

The value uses the HTML targetting rules to name/create the window
to receive the value of the link.  The first time the link is
accessed, a window with the specified name is created.  The next
time the user clicks on a link with the same target, that window
will receive the content of the link if it is still present, or it
will be created again if it has been closed.  A target named
"_blank" is special and will always create a new window.

The "link_target" option can also be computed dynamically.  See
COMPUTED OPTIONS for details.

=item * 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 COMPUTED
OPTIONS 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. The function
CGI::escapeHTML() is available to properly escape HTML characters in
dynamically-generated titles.

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.

=item * landmark_padding = 1000

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.

=item * image_padding = 25

=item * pad_left = 50

=item * 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.

=back

=head2 B3. Track Sections

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:

 [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:

=over

docs/pod/CONFIGURE_HOWTO.pod  view on Meta::CPAN

techniques.  See http://httpd.apache.org/docs/howto/auth.html for
the full details.

You can also limit individual tracks to certain individuals or
organizations.  Unless the stated requirements are met, the track will
not appear on the main screen or any of the configuration screens.  To
set this up, add a "restrict" option to the track you wish to make
off-limits:

	[PROPRIETARY]
	feature = etc
	glyph   = etc
	restrict = Order deny,allow
		   deny from all
		   allow from localhost .cshl.edu .ebi.ac.uk

The value of the restrict option is identical to the Apache
authorization directives and can include any of the directives
"Order," "Satisfy," "deny from," "allow from," "require valid-user" or
"require user."  The only difference is that the "require group"
directive is not supported, since the location of Apache's group file
is not passed to CGI scripts.  Note that username/password
authentication must be turned on in httpd.conf and the user must have
successfully authenticated himself in order for the username to be
available.

As with other gbrowse options, restrict can be a code subroutine.  The
subroutine will be called with three arguments consisting of the host,
ip address and authenticated user.  It should return a true value to
allow access to the track, or a false value to forbid it.  This can be
used to implement group-based authorization or more complex schemes.

Here is an example that uses the Text::GenderFromName to allow access
if the user's name sounds female and forbids access if the name sounds
male.  (It might be useful for an X-chromosome annotation site.)

    restrict = sub {
	       my ($host,$ip,$user) = @_;
	       return unless defined $user;
	       use Text::GenderFromName qw(gender);
	       return gender($user) eq 'f';
	     }

You should be aware that the username will only be defined if username
authentication is turned on and the user has successfully
authenticated himself against Apache's user database using the correct
password.  In addition, the hostname will only be defined if
HostnameLookups have been turned on in httpd.conf.  In the latter
case, you can convert the IP address into a hostname using this piece
of code:
    
    use Socket;
    $host = gethostbyaddr(inet_aton($addr),AF_INET);

Note that this may slow down the response time of gbrowse noticeably
if you have a slow DNS name server.

Another thing to be aware of when restricting access to an entire
database is that that even though the database itself will not be
accessible to unauthorized users, the name of the database will still
be available from the popup "Data Source" menu.  If you wish even the
name to be suppressed from view by unauthorized users, add the
following line to the [GENERAL] section of the configuration file of
the database you wish to suppress:

    restrict = require valid-user

The syntax described earlier for restricting access to tracks by
hostname, IP address or username holds true for restricting the
visibility of the database on the Data Source popup menu.

=head1 F. DISPLAYING GENETIC AND RH MAPS

GBrowse can be tweaked to make it more suitable for displaying genetic
and radiation hybrid maps.  

The main issue is that the Bio::DB::GFF database expects coordinates
to be positive integers, not fractions, but genetic and RH maps use
floating point numbers.  Working around this is a bit of an ugly hack.
Before loading your data you must multiply all your coordinates by a
constant power of 10 in order to convert them into integers.  For
example, if a genetic map uses Morgan units ranging from 0 to 1.80,
you would multiple by 100 to create a map in ranging from 0 to 180.

Create a GFF file containing the markers in modified coordinates and
load it as usual.  Now you must tell GBrowse to reverse these changes.
Enter the following options into the [GENERAL] section of the
configuration file:

 units = M
 unit_divider = 100

These two options tell GBrowse to use "M" (Morgan) units, and to
divide all coordinates by 100.  GBrowse will automatically display the
scale using the most appropriate units, so the displayed map will
typically be drawn using cM units.

=head1 G. CHANGING THE LOCATION OF THE CONFIGURATION FILES

If you wish to change the location of the gbrowse.conf configuration
file directory, you must manually edit the gbrowse CGI script.  Open
the script in a text editor, and find this section:

 ###################################################################
 # Non-modperl users should change this variable if needed to point
 # to the directory in which the configuration files are stored.
 #
 use constant CONF_DIR => '/usr/local/apache/conf/gbrowse.conf';
 #
 ###################################################################

Change the definition of CONF_DIR to the desired location of the
configuration files.

An alternative, for users of mod_perl only, is to add the GBrowseConf
per-directory variable to the configuration for the directory in which
the gbrowse script lives.  This variable overrides the CONF_DIR value.
For example:

 <Directory /usr/local/apache/cgi-perl>
   SetHandler      perl-script
   PerlHandler     Apache::Registry
   PerlSendHeader  On
   Options         +ExecCGI
   PerlSetVar      GBrowseConf /etc/gbrowse.conf
 </Directory>

=head1 H. USING DAS (DISTRIBUTED ANNOTATION SYSTEM) DATABASES

You may insert features from a DAS source into any named track. Create