Ace::Graphics::Panel - PNG graphics of Ace::Sequence::Feature objects
use Ace::Sequence;
use Ace::Graphics::Panel;
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;
my $panel = Ace::Graphics::Panel->new(
-segment => $cosmid,
-width => 800
);
$panel->add_track(arrow => $cosmid,
-bump => 0,
-tick=>2);
$panel->add_track(transcript => \@transcripts,
-fillcolor => 'wheat',
-fgcolor => 'black',
-key => 'Curated Genes',
-bump => +1,
-height => 10,
-label => 1);
my $boxes = $panel->boxes;
print $panel->png;
The Ace::Graphics::Panel class provides drawing and formatting services for
Ace::Sequence::Feature objects or Das::Segment::Feature objects.
Typically you will begin by creating a new Ace::Graphics::Panel object, passing
it the width of the visual display and the length of the segment.
You will then call
add_track() one or more times to add sets of related
features to the picture. 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.
Note that this modules depends on GD.
This section describes the class and object methods for Ace::Graphics::Panel.
There is only one constructor, the
new() method.
- $panel = Ace::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
------ ----- -------
-length Length of sequence segment, in bp 0
-segment An Ace::Sequence or Das::Segment none
object, used to derive length if
not provided
-offset Base pair to place at extreme left $segment->start
of image.
-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
-keycolor Background color for the key printed 'cornsilk'
at bottom of panel (if any)
-keyspacing Spacing between key glyphs in the 10
key printed at bottom of panel
(if any)
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 = Ace::Graphics::Panel->new(-segment => $sequence,
-width => 800);
new() will return undef in case of an error. If the specified glyph
name is not a valid one, new() will throw an exception.
- $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",
each corresponding to a sequence feature. There are different glyph types,
but each track can only contain a single type of glyph. Options passed to
the 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. Currently, the following
glyphs are available:
Name Description
---- -----------
box A filled rectangle, nondirectional.
ellipse A filled ellipse, nondirectional.
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.
segments A set of filled rectangles connected by solid lines.
Used for interrupted features, such as gapped
alignments.
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 arrow that indicates
the direction of transcription is the last exon
itself.
primers Two inward pointing arrows connected by a line.
Used for STSs.
toomany A "cloud", to indicate too many features to show
individually. This is a placeholder that will be
replaced by something more clever, such as a histogram
or density plot.
group A group of related features connected by a dashed line.
This is used internally by the Track class and should
not be called explicitly.
If the glyph name is omitted from add_track(), the "box"
glyph will be used by default.
The @options array is a list of name/value pairs that control the attributes
of the track. The options are in turn passed to the glyphs. Each glyph has
its own specialized subset of options, but some are shared by all glyphs:
Option Description Default
------ ----------- -------
-glyph Glyph to use none
-fgcolor Foreground color black
-outlinecolor black
Synonym for -fgcolor
-bgcolor Background color white
-fillcolor Interior color of filled turquoise
images
-linewidth Width of lines drawn by 1
glyph
-height Height of glyph 10
-font Glyph font gdSmallFont
-label Whether to draw a label false
-bump Bump direction 0
-connect_groups false
Connect groups by a
dashed line (see below)
-key Show this track in the undef
key
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 Ace::Graphics::Panel-> color_names()
method.
The background color is used for the background color of the track itself.
The foreground color controls the color of lines and strings. The interior
color is used for filled objects such as boxes.
The -label argument controls whether or not the ID of the feature should be
printed next to the feature. It is accepted by most, but not all of the
glyphs.
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 -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.
If present, the -glyph argument overrides the glyph given in the first or
second argument.
add_track() returns an Ace::Graphics::Track 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().
Typical usage is:
$panel->add_track( thistle => \@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.
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. To
connect the groups by a dashed line, pass the -connect_groups argument
with a true value. For example:
$panel->add_track(segments => [[$abc_5,$abc_3],
[$xxx_5,$xxx_3],
[$yyy_5,$yyy_3]],
-connect_groups => 1);
- $gd = $panel->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.
- $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.
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
length() Get/set length of segment (bp)
pad_top() Get/set top padding
pad_left() Get/set left padding
pad_bottom() Get/set bottom padding
pad_right() Get/set right padding
The following methods are used internally, but may be useful for those
implementing new glyph types.
- @names = Ace::Graphics::Panel->color_names
- Return the symbolic names of the colors recognized by the
panel object. In a scalar context, returns an array reference.
- @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)
- 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.
Please report them.
Ace::Sequence,Ace::Sequence::Feature, Ace::Graphics::Track,Ace::Graphics::Glyph,
GD
Lincoln Stein <
[email protected]>.
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.