CONSTRUCTORS

$panel = Bio::Graphics::Panel->new(@options)

The new() method creates a new panel object. The options are a set of tag/value pairs as follows:

  Option      Value                                  Default
  ------      -----                                  -------

  -offset     Base pair to place at extreme left     none
              of image, in zero-based coordinates

  -length     Length of sequence segment, in bp      none

  -start      Start of range, in 1-based             none
              coordinates.

  -stop       Stop of range, in 1-based              none
              coordinates.

  -end        Same as -stop.

  -segment    A Bio::SeqI or Das::Segment            none
              object, used to derive sequence
              range if not otherwise specified.

  -width      Desired width of image, in pixels      600

  -spacing    Spacing between tracks, in pixels      5

  -pad_top    Additional whitespace between top      0
              of image and contents, in pixels

  -pad_bottom Additional whitespace between top      0
              of image and bottom, in pixels

  -pad_left   Additional whitespace between left     0
              of image and contents, in pixels

  -pad_right  Additional whitespace between right    0
              of image and bottom, in pixels

  -bgcolor    Background color for the panel as a    white
              whole

  -key_color  Background color for the key printed   wheat
              at bottom of panel (if any)

  -key_spacing Spacing between key glyphs in the     10
               key printed at bottom of panel
               (if any)

  -key_font    Font to use in printed key            gdMediumBoldFont
               captions.

  -key_style   Whether to print key at bottom of     none
               panel ("bottom"), between each
               track ("between"), to the left of
               each track ("left"), to the right
               of each track ("right") or
               not at all ("none").

  -add_category_labels                               false
               Whether to add the "category" to
               the track key. The category is
               an optional argument that can
               be attached to each track. If
               a category is present, and this
               option is true, then the category
               will be added to the track label
               in parentheses. For example, if
               -key is "Protein matches" and
               -category is "vertebrate", then
               the track will be labeled
               "Protein matches (vertebrate)".

  -auto_pad    If "left" or "right" keys are in use  true
               then setting auto_pad to a true value
               will allow the panel to adjust its
               width in order to accomodate the
               length of the longest key.

  -empty_tracks What to do when a track is empty.    suppress
              Options are to suppress the track
              completely ("suppress"), to show just
              the key in "between" mode ("key"),
              to draw a thin grey line ("line"),
              or to draw a dashed line ("dashed").

  -flip       flip the drawing coordinates left     false
              to right, so that lower coordinates
              are to the right.  This can be
              useful for drawing (-) strand
              features.

  -all_callbacks Whether to invoke callbacks on      false
               the automatic "track" and "group"
               glyphs.

  -grid        Whether to draw a vertical grid in    false
               the background.  Pass a scalar true
               value to have a grid drawn at
               regular intervals (corresponding
               to the minor ticks of the arrow
               glyph).  Pass an array reference
               to draw the grid at the specified
               positions.

  -gridcolor   Color of the grid                     lightcyan

  -gridmajorcolor Color of grid major intervals      cyan

  -extend_grid If true, extend the grid into the pad false
               top and pad_bottom regions

  -background  An image or callback to use for the   none
               background of the image. Will be
               invoked I<before> drawing the grid.

  -postgrid    An image or callback to use for the   none
               background of the image.  Will be 
               invoked I<after> drawing the grid.

  -truecolor   Create a truecolor (24-bit) image.    false
               Useful when working with the
               "image" glyph.

  -truetype    Render text using scaleable vector    false
               fonts rather than bitmap fonts.

  -image_class To create output in scalable vector
               graphics (SVG), optionally pass the image
               class parameter 'GD::SVG'. Defaults to
               using vanilla GD. See the corresponding
               image_class() method below for details.

  -link, -title, -target
               These options are used when creating imagemaps
               for display on the web.  See L</"Creating Imagemaps">.
    

Typically you will pass new() an object that implements the Bio::RangeI interface, providing a length() method, from which the panel will derive its scale.

  $panel = Bio::Graphics::Panel->new(-segment => $sequence,
                                     -width   => 800);
    

new() will return undef in case of an error.

Note that if you use the "left" or "right" key styles, you are responsible for allocating sufficient -pad_left or -pad_right room for the labels to appear. The necessary width is the number of characters in the longest key times the font width (gdMediumBoldFont by default) plus 3 pixels of internal padding. The simplest way to calculate this is to iterate over the possible track labels, find the largest one, and then to compute its width using the formula:

  $width = gdMediumBoldFont->width * length($longest_key) +3;
    

In order to obtain scalable vector graphics (SVG) output, you should pass new() the -image_class=>'GD::SVG' parameter. This will cause Bio::Graphics::Panel to load the optional GD::SVG module. See the gd() and svg() methods below for additional information.

You can tile an image onto the panel either before or after it draws the grid. Simply provide the filename of the image in the -background or -postgrid options. The image file must be of type PNG, JPEG, XBM or GIF and have a filename ending in .png, .jpg, .jpeg, .xbm or .gif.

You can also pass a code ref for the -background or -postgrid option, in which case the subroutine will be invoked at the appropriate time with the GD::Image object and the Panel object as its two arguments. You can then use the panel methods to map base pair coordinates into pixel coordinates and do some custom drawing. For example, this code fragment will draw a gray rectangle between bases 500 and 600 to indicate a "gap" in the sequence:

  my $panel = Bio::Graphics::Panel->new(-segment=>$segment,
                                        -grid=>1,
                                        -width=>600,
                                        -postgrid=> \&draw_gap);
  sub gap_it {
     my $gd    = shift;
     my $panel = shift;
     my ($gap_start,$gap_end) = $panel->location2pixel(500,600);
     my $top                  = $panel->top;
     my $bottom               = $panel->bottom;
     my $gray                 = $panel->translate_color('gray');
     $gd->filledRectangle($gap_start,$top,$gap_end,$bottom,$gray);
}
    

The -truetype argument will activate rendering of labels using antialiased vector fonts. If it is a value of "1", then labels will be rendered using the default font (Verdana). Pass a font name to use this font as the default:

  -truetype => 'Times New Roman',
    

Note that you can change the font on a track-by-track basis simply by using a truetype font name as add_track()'s -font argument.

OBJECT METHODS

$track = $panel->add_track($glyph,$features,@options)

The add_track() method adds a new track to the image.

Tracks are horizontal bands which span the entire width of the panel. Each track contains a number of graphical elements called "glyphs", corresponding to a sequence feature.

There are a large number of glyph types. By default, each track will be homogeneous on a single glyph type, but you can mix several glyph types on the same track by providing a code reference to the -glyph argument. Other options passed to add_track() control the color and size of the glyphs, whether they are allowed to overlap, and other formatting attributes. The height of a track is determined from its contents and cannot be directly influenced.

The first two arguments are the glyph name and an array reference containing the list of features to display. The order of the arguments is irrelevant, allowing either of these idioms:

  $panel->add_track(arrow => \@features);
  $panel->add_track(\@features => 'arrow');
    

The glyph name indicates how each feature is to be rendered. A variety of glyphs are available, and the number is growing. You may omit the glyph name entirely by providing a -glyph argument among @options, as described below.

Currently, the following glyphs are available:

  Name        Description
  ----        -----------

  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.

  arrow       An arrow; can be unidirectional or bidirectional.
              It is also capable of displaying a scale with
              major and minor tickmarks, and can be oriented
              horizontally or vertically.

  box         A filled rectangle, nondirectional. Subfeatures are ignored.

  cds         Draws CDS features, using the phase information to
              show the reading frame usage.  At high magnifications
              draws the protein translation.

  crossbox    A box with a big "X" inside it.

  diamond     A diamond, useful for point features like SNPs.

  dna         At high magnification draws the DNA sequence.  At
              low magnifications draws the GC content.

  dot         A circle, useful for point features like SNPs, stop
              codons, or promoter elements.

  ellipse     An oval.

  extending_arrow
              Similar to arrow, but a dotted line indicates when the
              feature extends beyond the end of the canvas.

  generic     A filled rectangle, nondirectional. Subfeatures are shown
              as rectangles that are not connected together.

  graded_segments
              Similar to segments, but the intensity of the color
              is proportional to the score of the feature.  This
              is used for showing the intensity of blast hits or
              other alignment features.

  group       A group of related features connected by a dashed line.
              This is used internally by Panel.

  image       A pixmap image that will be layered on top of the graphic.

  heterogeneous_segments
              Like segments, but you can use the source field of the feature
              to change the color of each segment.

  line        A simple line.

  pinsertion  A triangle designed to look like an insertion location
              (e.g. a transposon insertion).

  processed_transcript  multi-purpose representation of a spliced mRNA, including
                        positions of UTRs

  primers     Two inward pointing arrows connected by a line.
              Used for STSs.

  redgreen_box A box that changes from green->yellow->red as the score
              of the feature increases from 0.0 to 1.0.  Useful for
              representing microarray results.

  rndrect     A round-cornered rectangle.

  segments    A set of filled rectangles connected by solid lines.
              Used for interrupted features, such as gapped
              alignments.

  ruler_arrow An arrow with major and minor tick marks and interval
              labels.

  toomany     Tries to show many features as a cloud.  Not very successful.

  track       A group of related features not connected by a line.
              This is used internally by Panel.

  transcript  Similar to segments, but the connecting line is
              a "hat" shape, and the direction of transcription
              is indicated by a small arrow.

  transcript2  Similar to transcript, but the direction of
              transcription is indicated by a terminal exon
              in the shape of an arrow.

  translation 1, 2 and 3-frame translations.  At low magnifications,
              can be configured to show start and stop codon locations.
              At high magnifications, shows the multi-frame protein
              translation.

  triangle    A triangle whose width and orientation can be altered.

  xyplot      Histograms and other graphs plotted against the genome.

  stackedplot A column plot showing multiple data series across multiple categories.

  ternary_plot Ternary (triangle) plots.

  whiskerplot Box and whisker plot for statistical data
    

If the glyph name is omitted from add_track(), the "generic" glyph will be used by default. To get more information about a glyph, run perldoc on "Bio::Graphics::Glyph::glyphname", replacing "glyphname" with the name of the glyph you are interested in.

The "box" glyph is optimized for single features with no subfeatures. If you are drawing such a feature, using "box" will be noticeably faster than "generic."

The @options array is a list of name/value pairs that control the attributes of the track. Some options are interpretered directly by the track. Others are passed down to the individual glyphs (see "GLYPH OPTIONS"). The following options are track-specific:

  Option      Description                  Default
  ------      -----------                  -------

  -tkcolor    Track color                  white

  -glyph      Glyph class to use.         "generic"

  -color_series Dynamically choose         false
                bgcolor.

  -stylesheet Bio::Das::Stylesheet to     none
              use to generate glyph
              classes and options.
    

-tkcolor controls the background color of the track as a whole.

-glyph controls the glyph type. If present, it supersedes the glyph name given in the first or second argument to add_track(). The value of -glyph may be a constant string, a hash reference, or a code reference. In the case of a constant string, that string will be used as the class name for all generated glyphs. If a hash reference is passed, then the feature's primary_tag() will be used as the key to the hash, and the value, if any, used to generate the glyph type. If a code reference is passed, then this callback will be passed arguments consisting of the feature and the panel object. The callback is expected to examine the feature and return a glyph name as its single result.

Example:

  $panel->add_track(\@exons,
                    -glyph => sub { my ($feature,$panel) = @_;
                                    $feature->source_tag eq 'curated'
                                          ? 'ellipse' : 'box'; }
                    );
    

The -stylesheet argument is used to pass a Bio::Das stylesheet object to the panel. This stylesheet will be called to determine both the glyph and the glyph options. If both a stylesheet and direct options are provided, the latter take precedence.

The -color_series argument causes the track to ignore the -bgcolor setting and instead to assign glyphs a series of contrasting colors. This is usually used in combination with -bump=>'overlap' in order to create overlapping features. A true value activates the color series. You may adjust the default color series using the -color_cycle option, which is either a reference to an array of Bio::Graphics color values, or a space-delimited string of color names/value.

If successful, add_track() returns an Bio::Graphics::Glyph object. You can use this object to add additional features or to control the appearance of the track with greater detail, or just ignore it. Tracks are added in order from the top of the image to the bottom. To add tracks to the top of the image, use unshift_track().

Adding groups of features: It is not uncommon to add a group of features which are logically connected, such as the 5' and 3' ends of EST reads. To group features into sets that remain on the same horizontal position and bump together, pass the sets as an anonymous array. For example:

  $panel->add_track(segments => [[$abc_5,$abc_3],
                                 [$xxx_5,$xxx_3],
                                 [$yyy_5,$yyy_3]]
                    );
    

Typical usage is:

 $panel->add_track( transcript    => \@genes,
                    -fillcolor =>  'green',
                    -fgcolor   =>  'black',
                    -bump      =>  +1,
                    -height    => 10,
                    -label     => 1);
    

The track object is simply a specialized type of glyph. See Bio::Graphics::Glyph for a description of the methods that it supports.

$track = unshift_track($glyph,$features,@options)

unshift_track() works like add_track(), except that the new track is added to the top of the image rather than the bottom.

$track = $panel->insert_track($position,$glyph,$features,@options)

This works like add_track(), but the track is inserted into the indicated position. The track will be inserted before the indicated position; thus specify a track of 0 to insert the new track at the beginning.

$gd = $panel->gd([$gd])

The gd() method lays out the image and returns a GD::Image object containing it. You may then call the GD::Image object's png() or jpeg() methods to get the image data.

Optionally, you may pass gd() a preexisting GD::Image object that you wish to draw on top of. If you do so, you should call the width() and height() methods first to ensure that the image has sufficient dimensions.

If you passed new() the -image_class=>'GD::SVG' parameter, the gd() method returns a GD::SVG::Image object. This object overrides GD::Image methods in order to generate SVG output. It behaves exactly as described for GD::Image objects with one exception: it implements and svg() method instead of the png() or jpeg() methods. Currently there is no direct access to underlying SVG calls but this is subject to change in the future.

$png = $panel->png

The png() method returns the image as a PNG-format drawing, without the intermediate step of returning a GD::Image object.

$svg = $panel->svg

The svg() method returns the image in an XML-ified SVG format.

$panel->finished

Bio::Graphics creates memory cycles. When you are finished with the panel, you should call its finished() method. Otherwise you will have memory leaks. This is only an issue if you're going to create several panels in a single program.

$image_class = $panel->image_class

The image_class() method returns the current drawing package being used, currently one of GD or GD::SVG. This is primarily used internally to ensure that calls to GD's exported methods are called in an object-oriented manner to avoid compile time undefined string errors. This is usually not needed for external use.

$image_package = $panel->image_package

This accessor method, like image_class() above is provided as a convenience. It returns the current image package in use, currently one of GD::Image or GD::SVG::Image. This is not normally used externally.

$polygon_package = $panel->polygon_package

This accessor method, like image_package() above is provided as a convenience. It returns the current polygon package in use, currently one of GD::Polygon or GD::SVG::Polygon. This is not normally used externally except in the design of glyphs.

$boxes = $panel->boxes

@boxes = $panel->boxes

The boxes() method returns a list of arrayrefs containing the coordinates of each glyph. The method is useful for constructing an image map. In a scalar context, boxes() returns an arrayref. In an list context, the method returns the list directly.

Each member of the list is an arrayref of the following format:

  [ $feature, $x1, $y1, $x2, $y2, $track ]
    

The first element is the feature object; either an Ace::Sequence::Feature, a Das::Segment::Feature, or another Bioperl Bio::SeqFeatureI object. The coordinates are the topleft and bottomright corners of the glyph, including any space allocated for labels. The track is the Bio::Graphics::Glyph object corresponding to the track that the feature is rendered inside.

$boxes = $panel->key_boxes

@boxes = $panel->key_boxes

Returns the positions of the track keys as an arrayref or a list, depending on context. Each value in the list is an arrayref of format:

 [ $key_text, $x1, $y1, $x2, $y2, $track ]
    

$position = $panel->track_position($track)

After calling gd() or boxes(), you can learn the resulting Y coordinate of a track by calling track_position() with the value returned by add_track() or unshift_track(). This will return undef if called before gd() or boxes() or with an invalid track.

$rotate = $panel->rotate([$new_value])

Gets or sets the "rotate" flag. If rotate is set to true (default false), then calls to gd(), png(), gif(), boxes(), and image_and_map() will all return an image and/or imagemap that has been rotated to the right by 90 degrees. This is mostly useful for drawing karyotypes with the ideogram glyph, in order to rotate the chromosomes into the usual vertical position.

@pixel_coords = $panel->location2pixel(@feature_coords)

Public routine to map feature coordinates (in base pairs) into pixel coordinates relative to the left-hand edge of the picture. If you define a -background callback, the callback may wish to invoke this routine in order to translate base coordinates into pixel coordinates.

$left = $panel->left

$right = $panel->right

$top = $panel->top

$bottom = $panel->bottom

Return the pixel coordinates of the drawing area of the panel, that is, exclusive of the padding.

Options and Callbacks

   sub callback {
      my ($feature,$option_name,$part_no,$total_parts,$glyph) = @_;
      # do something which results in $option_value being set
      return $option_value;
   }

The five arguments are $feature, a reference to the IO::SeqFeatureI object, $option_name, the name of the option to configure, $part_no, an integer index indicating which subpart of the feature is being drawn, $total_parts, an integer indicating the total number of subfeatures in the feature, and finally $glyph, the Glyph object itself. The latter fields are useful in the case of treating the first or last subfeature differently, such as using a different color for the terminal exon of a gene. Usually you will only need to examine the first argument. This example shows a callback examining the score() attribute of a feature (possibly a BLAST hit) and return the color "red" for high-scoring features, and "green" for low-scoring features:

  sub callback {
     my $feature = shift;
     if ($feature->score > 90) {
       return 'red';
     else {
       return 'green';
    }
  }

The callback should return a string indicating the desired value of the option. To tell the panel to use the default value for this option, return the string "*default*".

The callback for -grid is slightly different because at the time this option is needed there is no glyph defined. In this case, the callback will get two arguments: the feature and the panel object:

 -glyph => sub {
      my ($feature,$panel) = @_;
      return 'gene' if $panel->length < 10_000;
      return 'box';
    }

When you install a callback for a feature that contains subparts, the callback will be invoked first for the top-level feature, and then for each of its subparts (recursively). You should make sure to examine the feature's type to determine whether the option is appropriate.

Also be aware that some options are only called for subfeatures. For example, when using multi-segmented features, the "bgcolor" and "fgcolor" options apply to the subfeatures and not to the whole feature; therefore the corresponding callbacks will only be invoked for the subfeatures and not for the top-level feature. To get information that applies to the top-level feature, use the glyph's parent_feature() method. This returns:

   * the parent if called with no arguments or with an argument of (1)
   * the parent's parent if called with an argument of (2)
   * the parent's parent's parent if called with an argument of (3)
   * etc.

The general way to take advantage of this feature is:

   sub callback {
      my ($feature,$option_name,$part_no,$total_parts,$glyph) = @_;
      my $parent = $glyph->parent_feature();

      # do something which results in $option_value being set
      return $option_value;
   }

or, more concisely:

   sub callback {
      my $feature = shift;  # first argument
      my $glyph   = pop;    # last argument
      my $parent = $glyph->parent_feature();

      # do something which results in $option_value being set
      return $option_value;
   }

Some glyphs deliberately disable recursion into subparts. The "track", "group", "transcript", "transcript2" and "segments" glyphs selectively disable the -bump, -label and -description options. This is to avoid, for example, a label being attached to each exon in a transcript, or the various segments of a gapped alignment bumping each other. You can override this behavior and force your callback to be invoked by providing add_track() with a true -all_callbacks argument. In this case, you must be prepared to handle configuring options for the "group" and "track" glyphs.

In particular, this means that in order to control the -bump option with a callback, you should specify -all_callbacks=>1, and turn on bumping when the callback is in the track or group glyphs.

The -subpart_callbacks options is similar, except that when this is set to true callbacks are invoked for the main glyph and its subparts. This option only affects the -label and -description options.

ACCESSORS

Note that in most cases you must change attributes prior to invoking gd(), png() or boxes(). These three methods all invoke an internal layout() method which places the tracks and the glyphs within them, and then caches the result.

   Accessor Name      Description
   -------------      -----------

   width()            Get/set width of panel
   spacing()          Get/set spacing between tracks
   key_spacing()      Get/set spacing between keys
   length()           Get/set length of segment (bp)
   flip()             Get/set coordinate flipping
   pad_top()          Get/set top padding
   pad_left()         Get/set left padding
   pad_bottom()       Get/set bottom padding
   pad_right()        Get/set right padding
   start()            Get the start of the sequence (bp; read only)
   end()              Get the end of the sequence (bp; read only)
   left()             Get the left side of the drawing area (pixels; read only)
   right()            Get the right side of the drawing area (pixels; read only)

COLOR METHODS

@names = Bio::Graphics::Panel->color_names

Return the symbolic names of the colors recognized by the panel object. In a scalar context, returns an array reference.

($red,$green,$blue) = Bio::Graphics::Panel->color_name_to_rgb($color)

Given a symbolic color name, returns the red, green, blue components of the color. In a scalar context, returns an array reference to the rgb triplet. Returns undef for an invalid color name.

@rgb = $panel->rgb($index)

Given a GD color index (between 0 and 140), returns the RGB triplet corresponding to this index. This method is only useful within a glyph's draw() routine, after the panel has allocated a GD::Image and is populating it.

$index = $panel->translate_color($color)

Given a color, returns the GD::Image index. The color may be symbolic, such as "turquoise", or a #RRGGBB triple, as in #F0E0A8. This method is only useful within a glyph's draw() routine, after the panel has allocated a GD::Image and is populating it.

$panel->set_pen($width,$color)

Changes the width and color of the GD drawing pen to the values indicated. This is called automatically by the GlyphFactory fgcolor() method. It returns the GD value gdBrushed, which should be used for drawing.

Creating Imagemaps

Here is a synopsis of how to use image_and_map() in a CGI script, using CGI.pm calls to provide the HTML scaffolding:

   print h2('My Genome');

   my ($url,$map,$mapname) =
       $panel->image_and_map(-root => '/var/www/html',
                             -url  => '/tmpimages',
                             -link => 'http://www.google.com/search?q=$name');

   print img({-src=>$url,-usemap=>"#$mapname"});

   print $map;

We call image_and_map() with various arguments (described below) to generate a three element list consisting of the URL at which the image can be accessed, an HTML fragment containing the clickable imagemap data, and the name of the map. We print out an <image> tag that uses the URL of the map as its src attribute and the name of the map as the value of its usemap attribute. It is important to note that we must put a "#" in front of the name of the map in order to indicate that the map can be found in the same document as the <image> tag. Lastly, we print out the map itself.

($url,$map,$mapname) = $panel->image_and_map(@options)

Create the image in a web-accessible directory and return its URL, its clickable imagemap, and the name of the imagemap. The following options are recognized:

 Option        Description
 ------        -----------

 -url          The URL to store the image at.


 -root         The directory path that should be appended to the
               start of -url in order to obtain a physical
               directory path.
 -link         A string pattern or coderef that will be used to
               generate the outgoing hypertext links for the imagemap.

 -title        A string pattern or coderef that will be used to
               generate the "title" tags of each element in the imagemap
               (these appear as popup hint boxes in certain browsers).

 -target       A string pattern or coderef that will be used to
               generate the window target for each element.  This can
               be used to pop up a new window when the user clicks on
               an element.

 -mapname      The name to use for the E<lt>mapE<gt> tag.  If not provided,
               a unique one will be autogenerated for you.
    

This method returns a three element list consisting of the URL at which the image has been written to, the imagemap HTML, and the name of the map. Usually you will incorporate this information into an HTML document like so:

  my ($url,$map,$mapname) =
          $panel->image_and_map(-link=>'http://www.google.com/search?q=$name');
  print qq(<img src="$url" usemap="#$mapname">),"\n";
  print $map,"\n";
    

$url = $panel->create_web_image($url,$root)

Create the image, write it into the directory indicated by concatenating $root and $url (i.e. "$root/$url"), and return $url.

$map = $panel->create_web_map('mapname',$linkrule,$titlerule,$targetrule)

Create a clickable imagemap named "mapname" using the indicated rules to generate the hypertext links, the element titles, and the window targets for the graphical elements. Return the HTML for the map, including the enclosing <map> tag itself.

To use this method effectively, you will need a web server and an image directory in the document tree that is writable by the web server user. For example, if your web server's document root is located at /var/www/html, you might want to create a directory named "tmpimages" for this purpose:

  mkdir /var/www/html/tmpimages
  chmod 1777 /var/www/html/tmpimages

The 1777 privilege will allow anyone to create files and subdirectories in this directory, but only the owner of the file will be able to delete it.

When you call image_and_map(), you must provide it with two vital pieces of information: the URL of the image directory and the physical location of the web server's document tree. In our example, you would call:

  $panel->image_and_map(-root => '/var/www/html',-url=>'/tmpimages');

If you are working with virtual hosts, you might wish to provide the hostname:portnumber part of the URL. This will work just as well:

  $panel->image_and_map(-root => '/var/www/html',
                        -url  => 'http://myhost.com:8080/tmpimages');

If you do not provide the -root argument, the method will try to figure it out from the DOCUMENT_ROOT environment variable. If you do not provide the -url argument, the method will assume "/tmp".

During execution, the image_and_map() method will generate a unique name for the image using the Digest::MD5 module. You can get this module on CPAN and it must be installed in order to use image_and_map(). The imagename will be a long hexadecimal string such as "e7457643f12d413f20843d4030c197c6.png". Its URL will be /tmpimages/e7457643f12d413f20843d4030c197c6.png, and its physical path will be /var/www/html/tmpimages/e7457643f12d413f20843d4030c197c6.png

In addition to providing directory information, you must also tell image_and_map() how to create outgoing links for each graphical feature, and, optionally, how to create the "hover title" (the popup yellow box displayed by most modern browsers), and the name of the window or frame to link to when the user clicks on it.

There are three ways to specify the link destination:

1.

By configuring one or more tracks with a -link argument.

2.

By configuring the panel with a -link argument.

3.

By passing a -link argument in the call to image_and_map().

The -link argument can be either a string or a coderef. If you pass a string, it will be interpreted as a URL pattern containing runtime variables. These variables begin with a dollar sign ($), and are replaced at run time with the information relating to the selected annotation. Recognized variables include:

     $name        The feature's name (display name)
     $id          The feature's id (eg, PK from a database)
     $class       The feature's class (group class)
     $method      The feature's method (same as primary tag)
     $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
     $length      Length of this feature
     $segstart    The left end of $ref displayed in the detailed view
     $segend      The right end of $ref displayed in the detailed view

For example, to link each feature to a Google search on the feature's description, use the argument:

  -link => 'http://www.google.com/search?q=$description'

Be sure to use single quotes around the pattern, or Perl will attempt to perform variable interpretation before image_and_map() has a chance to work on it.

You may also pass a code reference to -link, in which case the code will be called every time a URL needs to be generated for the imagemap. The subroutine will be called with two arguments, the feature and the Bio::Graphics::Panel object, and it should return the URL to link to, or an empty string if a link is not desired. Here is a simple example:

  -link => sub {
         my ($feature,$panel) = @_;
         my $type = $feature->primary_tag;
         my $name = $feature->display_name;
         if ($primary_tag eq 'clone') {
            return "http://www.google.com/search?q=$name";
         } else {
            return "http://www.yahoo.com/search?p=$name";
         }

The -link argument cascades. image_and_map() will first look for a -link option in the track configuration, and if that's not found, it will look in the Panel configuration (created during Bio::Graphics::Panel->new). If no -link configuration option is found in either location, then image_and_map() will use the value of -link passed in its argument list, if any.

The -title and -target options behave in a similar manner to -link. -title is used to assign each feature "title" and "alt" attributes. The "title" attribute is used by many browsers to create a popup hints box when the mouse hovers over the feature's glyph for a preset length of time, while the "alt" attribute is used to create navigable menu items for the visually impaired. As with -link, you can set the title by passing either a substitution pattern or a code ref, and the -title option can be set in the track, the panel, or the method call itself in that order of priority.

If not provided, image_and_map() will autogenerate its own title in the form "<method> <display_name> <seqid>:start..end".

The -target option can be used to specify the window or frame that clicked features will link to. By default, when the user clicks on a feature, the loaded URL will replace the current page. You can modify this by providing -target with the name of a preexisting or new window name in order to create effects like popup windows, multiple frames, popunders and the like. The value of -target follows the same rules as -title and -link, including variable substitution and the use of code refs.

NOTE: Each time you call image_and_map() it will generate a new image file. Images that are identical to an earlier one will reuse the same name, but those that are different, even by one pixel, will result in the generation of a new image. If you have limited disk space, you might wish to check the images directory periodically and remove those that have not been accessed recently. The following cron script will remove image files that haven't been accessed in more than 20 days.

30 2 * * * find /var/www/html/tmpimages -type f -atime +20 -exec rm {} \;