NAME
Bio::Graphics::Panel - Generate GD images of Bio::Seq objects
SYNOPSIS
# This script parses a GenBank or EMBL file named on the command
# line and produces a PNG rendering of it. Call it like this:
# render.pl my_file.embl | display -
use strict;
use Bio::Graphics;
use Bio::SeqIO;
my $file = shift or die "provide a sequence file as the argument";
my $io = Bio::SeqIO->new(-file=>$file) or die "could not create Bio::SeqIO";
my $seq = $io->next_seq or die "could not find a sequence in the file";
my @features = $seq->all_SeqFeatures;
# sort features by their primary tags
my %sorted_features;
for my $f (@features) {
my $tag = $f->primary_tag;
push @{$sorted_features{$tag}},$f;
}
my $panel = Bio::Graphics::Panel->new(
-length => $seq->length,
-key_style => 'between',
-width => 800,
-pad_left => 10,
-pad_right => 10,
);
$panel->add_track( arrow => Bio::SeqFeature::Generic->new(-start=>1,
-end=>$seq->length),
-bump => 0,
-double=>1,
-tick => 2);
$panel->add_track(generic => Bio::SeqFeature::Generic->new(-start=>1,
-end=>$seq->length),
-glyph => 'generic',
-bgcolor => 'blue',
-label => 1,
);
# general case
my @colors = qw(cyan orange blue purple green chartreuse magenta yellow aqua);
my $idx = 0;
for my $tag (sort keys %sorted_features) {
my $features = $sorted_features{$tag};
$panel->add_track($features,
-glyph => 'generic',
-bgcolor => $colors[$idx++ % @colors],
-fgcolor => 'black',
-font2color => 'red',
-key => "${tag}s",
-bump => +1,
-height => 8,
-label => 1,
-description => 1,
);
}
print $panel->png;
exit 0;DESCRIPTION
The Bio::Graphics::Panel class provides drawing and formatting services for any object that implements the Bio::SeqFeatureI interface, including Ace::Sequence::Feature and Das::Segment::Feature objects. It can be used to draw sequence annotations, physical (contig) maps, 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.
METHODS
This section describes the class and object methods for Bio::Graphics::Panel.
Typically you will begin by creating a new Bio::Graphics::Panel object, passing it the desired width of the image to generate and an origin and length describing the coordinate range to display. The Bio::Graphics::Panel->new() method has may configuration variables that allow you to control the appearance of the image.
You will then call add_track() one or more times to add sets of related features to the picture. add_track() places a new horizontal track on the image, and is likewise highly configurable. When you have added all the features you desire, you may call png() to convert the image into a PNG-format image, or boxes() to return coordinate information that can be used to create an imagemap.
CONSTRUCTORS
new() is the constructor for Bio::Graphics::Panel:
- $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. -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"). -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 lightcyanTypically 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;
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. 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. 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. 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.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 @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" -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 each feature in turn as its single argument. 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 = shift; $feature->source_tag eq 'curated' ? 'ellipse' : 'generic'; } );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.
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); - $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.
- $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.
- $png = $panel->png
-
The png() method returns the image as a PNG-format drawing, without the intermediate step of returning a GD::Image object.
- $boxes = $panel->boxes
- @boxes = $panel->boxes
-
The boxes() method returns the coordinates of each glyph, useful for constructing an image map. In a scalar context, boxes() returns an array ref. In an list context, the method returns the array directly.
Each member of the list is an anonymous array of the following format:
[ $feature, $x1, $y1, $x2, $y2 ]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.
- $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.
- @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.
GLYPH OPTIONS
Each glyph has its own specialized subset of options, but some are shared by all glyphs:
Option Description Default
------ ----------- -------
-fgcolor Foreground color black
-bgcolor Background color turquoise
-linewidth Width of lines drawn by 1
glyph
-height Height of glyph 10
-font Glyph font gdSmallFont
-fontcolor Primary font color black
-font2color Secondary font color turquoise
-label Whether to draw a label false
-description Whether to draw a false
description
-bump Bump direction 0
-sort_order Specify layout sort order "default"
-bump_limit Maximum number of levels undef (unlimited)
to bump
-strand_arrow Whether to indicate undef (false)
strandedness
-stranded Synonym for -strand_arrow undef (false)
-connector Type of connector to none
use to connect related
features. Options are
"solid," "hat", "dashed",
"quill" and "none".
-key Description of track for undef
use in key.
-all_callbacks Whether to invoke undef
callbacks for autogenerated
"track" and "group" glyphs
-box_subparts Return boxes around feature false
subparts rather than around the
feature itself.Specifying colors: Colors can be expressed in either of two ways: as symbolic names such as "cyan" and as HTML-style #RRGGBB triples. The symbolic names are the 140 colors defined in the Netscape/Internet Explorer color cube, and can be retrieved using the Bio::Graphics::Panel->color_names() method.
Foreground color: The -fgcolor option controls the foreground color, including the edges of boxes and the like.
Background color: The -bgcolor option controls the background used for filled boxes and other "solid" glyphs. The foreground color controls the color of lines and strings. The -tkcolor argument controls the background color of the entire track.
Track color: The -tkcolor option used to specify the background of the entire track.
Font color: The -fontcolor option controls the color of primary text, such as labels
Secondary Font color: The -font2color option controls the color of secondary text, such as descriptions.
Labels: The -label argument controls whether or not the ID of the feature should be printed next to the feature. It is accepted by all glyphs. By default, the label is printed just above the glyph and left aligned with it.
-label can be a constant string or a code reference. Values can be any of:
-label value Description
------------ -----------
0 Don't draw a label
1 Calculate a label based on primary tag of sequence
"a string" Use "a string" as the label
code ref Invoke the code reference to compute the labelA known bug with this naming scheme is that you can't label a feature with the string "1". To work around this, use "1 " (note the terminal space).
Descriptions: The -description argument controls whether or not a brief description of the feature should be printed next to it. By default, the description is printed just below the glyph and left-aligned with it. A value of 0 will suppress the description. A value of 1 will call the source_tag() method of the feature. A code reference will be invoked to calculate the description on the fly. Anything else will be treated as a string and used verbatim.
Connectors: A glyph can contain subglyphs, recursively. The top level glyph is the track, which contains one or more groups, which contain features, which contain subfeatures, and so forth. By default, the "group" glyph draws dotted lines between each of its subglyphs, the "segment" glyph draws a solid line between each of its subglyphs, and the "transcript" and "transcript2" glyphs draw hat-shaped lines between their subglyphs. All other glyphs do not connect their components. You can override this behavior by providing a -connector option, to explicitly set the type of connector. Valid options are:
"hat" an upward-angling conector
"solid" a straight horizontal connector
"quill" a decorated line with small arrows indicating strandedness
(like the UCSC Genome Browser uses)
"dashed" a horizontal dashed line.The -connector_color option controls the color of the connector, if any.
Collision control: The -bump argument controls what happens when glyphs collide. By default, they will simply overlap (value 0). A -bump value of +1 will cause overlapping glyphs to bump downwards until there is room for them. A -bump value of -1 will cause overlapping glyphs to bump upwards. The bump argument can also be a code reference; see below.
Keys: The -key argument declares that the track is to be shown in a key appended to the bottom of the image. The key contains a picture of a glyph and a label describing what the glyph means. The label is specified in the argument to -key.
box_subparts: Ordinarily, when you invoke the boxes() methods to retrieve the rectangles surrounding the glyphs (which you need to do to create clickable imagemaps, for example), the rectangles will surround the top level features. If you wish for the rectangles to surround subpieces of the glyph, such as the exons in a transcript, set box_subparts to a true value.
strand_arrow: If set to true, some glyphs will indicate their strandedness, usually by drawing an arrow. For this to work, the Bio::SeqFeature must have a strand of +1 or -1. The glyph will ignore this directive if the underlying feature has a strand of zero or undef.
sort_order: By default, features are drawn with a layout based only on the position of the feature, assuring a maximal "packing" of the glyphs when bumped. In some cases, however, it makes sense to display the glyphs sorted by score or some other comparison, e.g. such that more "important" features are nearer the top of the display, stacked above less important features. The -sort_order option allows a few different built-in values for changing the default sort order (which is by "left" position): "low_score" (or "high_score") will cause features to be sorted from lowest to highest score (or vice versa). "left" (or "default") and "right" values will cause features to be sorted by their position in the sequence. "longer" (or "shorter") will cause the longest (or shortest) features to be sorted first, and "strand" will cause the features to be sorted by strand: "+1" (forward) then "0" (unknown, or NA) then "-1" (reverse).
In all cases, the "left" position will be used to break any ties. To break ties using another field, options may be strung together using a "|" character; e.g. "strand|low_score|right" would cause the features to be sorted first by strand, then score (lowest to highest), then by "right" position in the sequence. Finally, a subroutine coderef can be provided, which should expect to receive two feature objects (via the special sort variables $a and $b), and should return -1, 0 or 1 (see Perl's sort() function for more information); this subroutine will be used without further modification for sorting. For example, to sort a set of database search hits by bits (stored in the features' "score" fields), scaled by the log of the alignment length (with "left" position breaking any ties):
sort_order = sub { ( $b->score/log($b->length)
<=>
$a->score/log($a->length) )
||
( $a->start <=> $b->start )
}bump_limit: When bumping is chosen, colliding features will ordinarily move upward or downward without limit. When many features collide, this can lead to excessively high images. You can limit the number of levels that features will bump by providing a numeric bump_limit option.
Options and Callbacks
Instead of providing a constant value to an option, you may subsitute a code reference. This code reference will be called every time the panel needs to configure a glyph. The callback will be called with three arguments like this:
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*".
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.
Some glyphs deliberately disable this recursive feature. 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.
ACCESSORS
The following accessor methods provide access to various attributes of the panel object. Called with no arguments, they each return the current value of the attribute. Called with a single argument, they set the attribute and return its previous value.
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
The following methods are used internally, but may be useful for those implementing new glyph types.
- @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.
BUGS
Please report them.
SEE ALSO
Bio::Graphics::Glyph, Bio::Graphics::Glyph::arrow, Bio::Graphics::Glyph::cds, Bio::Graphics::Glyph::crossbox, Bio::Graphics::Glyph::diamond, Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::dot, Bio::Graphics::Glyph::ellipse, Bio::Graphics::Glyph::extending_arrow, Bio::Graphics::Glyph::generic, Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::heterogeneous_segments, Bio::Graphics::Glyph::line, Bio::Graphics::Glyph::pinsertion, Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::rndrect, Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::redgreen_box, Bio::Graphics::Glyph::ruler_arrow, Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::transcript, Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::translation, Bio::Graphics::Glyph::triangle, Bio::Graphics::Glyph::xyplot, Bio::SeqI, Bio::SeqFeatureI, Bio::Das, GD
AUTHOR
Lincoln Stein <lstein@cshl.org>
Copyright (c) 2001 Cold Spring Harbor Laboratory
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.