Bio::Graphics::Panel - Generate GD images of Bio::Seq objects

SYNOPSIS

This is a simple GD-based renderer (diagram drawer) for DNA and
protein sequences.  It is used from Perl like this:

  use Bio::Graphics::Panel;

  # Create a series of Bio::SeqFeature objects. In this example,
  # we use AcePerl
  use Ace::Sequence;  # or any Bio::Seq factory
  my $db     = Ace->connect(-host=>'brie2.cshl.org',-port=>2005) or die;
  my $cosmid = Ace::Sequence->new(-seq=>'Y16B4A',
				  -db=>$db,-start=>-15000,-end=>15000) or die;
  my @transcripts = $cosmid->transcripts;

  # Let the drawing begin...
  my $panel = Bio:Graphics::Panel->new(
				      -segment => $cosmid,
				      -width  => 800
				     );


  $panel->add_track(arrow => $cosmid,
 		  -bump => 0,
 		  -tick=>2);

  $panel->add_track(transcript => \@transcripts,
 		    -bgcolor   =>  'wheat',
 		    -fgcolor   =>  'black',
                    -key       => 'Curated Genes',
 		    -bump      =>  +1,
 		    -height    =>  10,
 		    -label     =>  1);

  print $panel->png;

DESCRIPTION

The Bio::Graphics::Panel class provides drawing and formatting
services for any object that implements the Bio::SeqFeatureI
interface, including Ace::Sequence::Feature, Das::Segment::Feature and
Bio::DB::Graphics objects.  It can be used to draw sequence
annotations, physical (contig) maps, protein domains, or any other
type of map in which a set of discrete ranges need to be laid out on
the number line.

The module supports a drawing style in which each type of feature
occupies a discrete "track" that spans the width of the display.  Each
track will have its own distinctive "glyph", a configurable graphical
representation of the feature.

The module also supports a more flexible style in which several
different feature types and their associated glyphs can occupy the
same track.  The choice of glyph is under run-time control.

Semantic zooming (for instance, changing the type of glyph depending
on the density of features) is supported by a callback system for
configuration variables.  The module has built-in support for Bio::Das
stylesheets, and stylesheet-driven configuration can be intermixed
with semantic zooming, if desired.

You can add a key to the generated image using either of two key
styles.  One style places the key captions at the top of each track.
The other style generates a graphical key at the bottom of the image.

Note that this modules depends on GD.

BUILDING AND INSTALLING

From the directory in which this README file is located:

  % perl Makefile.PL
  % make test
  % make install

The last step may need to be run as root.

THE FEATURE_DRAW.PL SCRIPT

This module contains a simple script named "feature_draw.pl" that
takes a file of annotations and generates an image.  When first built,
the script lives in the "scripts" subdirectory.  After installation,
the script will be moved into your system-wide scripts directory
(usually /usr/bin or something similar).

There is a sample features file in the "eg" subdirectory.  After
building, but before installation, you can run the following command
from the directory in which this README file is located:

  %  scripts/feature_draw.pl eg/feature_data.txt | display -

This is piping the output directly to the "display" program, part of
the ImageMagick package.  Replace with your favorite PNG-capable
display program.

After installation, feature_draw.pl will be available on your command
path.  Run "man feature_draw.pl" to see the manual page, or use the -h
option to get a quick summary of usage.

THE GBROWSE CGI SCRIPT

The gbrowse script is a CGI script that will render features contained
in a Bio::DB::GFF database.  It implements a sequence browser that is
eerily similar to the one used by Wormbase
(http://www.wormbase.org/db/searches/hunter.cgi).  It is currently
under development, so little documentation is provided.  However, here
is the brief synopsis:

 1) install the following packages:

	Bio::Graphics
	Digest::MD5
	Bio::DB::GFF

    These can all be found on CPAN, with the exception of Bio::DB::GFF, which
    must be downloaded from the bioperl CVS site, http://www.bioperl.org

 2) Copy the file scripts/gbrowse to your CGI scripts directory, e.g.
    http://your.host/cgi-bin

 3) Create a subdirectory named gbrowse.conf which will hold your configuration
	files.  I suggest placing it with other web server configuration files,
	such as /usr/local/apache/conf/gbrowse.conf

 4) Modify the installed gbrowse script to point at the correct configuration
	file.  Find this line:

         my $CONF_DIR = '/usr/local/apache/conf/gbrowse.conf';

         and change it to wherever you put the gbrowse.conf directory.

 5) Copy the contents of eg/gbrowse/images into a directory in your
	web server document root, for example:

	   /usr/local/apache/htdocs/gbrowse/images

 	This contains a set of gif images used to create buttons.

 6) Create a directory in the web server document root that the
        script can write into.  This will be used to create
	temporary images before sending them to the user.  The
	directory should either be world writable, or owned by
	the "nobody" user.  I suggest a directory named "tmp"
	under the images directory.  For example:

	   /usr/local/apache/htdocs/gbrowse/images/tmp

 7) Copy the stylesheet file found in eg/gbrowse/gbrowse.css into
	your web server document root, for example:

           /usr/local/apache/htdocs/gbrowse/gbrowse.css

    This is the stylesheet that gives gbrowse its user-friendly appearance.

 8) Create a configuration file and place it into the gbrowse.conf 
	configuration directory.  You should start with the wormbase.conf 
	sample file located in eg/gbrowse/gbrowse.conf/wormbase.conf.

        There is some documentation embedded in the sample configuration 
	file.  You will need to adjust the [GENERAL] section to point to
	the database and host on which your database is located.

	At the minimum you should adjust the following options:

         a) database = dbi:mysql:database=wormbase;host=localhost
            This is the database name used by Bio::DB::GFF
        
         b) fasta_files = /var/www/elegans
            This is the location in which the FASTA files containing
		the raw DNA are located.

         c) stylesheet  = /gbrowse/gbrowse.css
             This is the URL for the stylesheet.

         d) buttons     = /gbrowse/images
             This is the URL for the static images

         e) tmpimages    = /gbrowse/images/tmp
             This is the location of the temporary
	     images directory.  This directory MUST
 	     be writable by the web server user, and
	     MUST be located under the document root.

	After the [GENERAL] section are a set of [FEATURE NAME] sections,
	that correspond to each of the sequence feature types 
	that you wish to make browsable.  The examples are very
	wormbase specific.  You will need to edit this heavily to
	suit the list of features you wish to display.

 9) Load the GFF database, following the instructions contained
	in the Bio::DB::GFF module.  Be careful.  The format
	of the GFF load file is very specific.

Let me know if you actually get this working.  More detailed
documentation and an install script are coming.

Lincoln Stein <lstein@cshl.org>
November 16, 2001