1Ace::Graphics::Panel(3)User Contributed Perl DocumentatioAnce::Graphics::Panel(3)
2
6 Ace::Graphics::Panel - PNG graphics of Ace::Sequence::Feature objects
7
9 use Ace::Sequence;
10 use Ace::Graphics::Panel;
11 my $db = Ace->connect(-host=>'brie2.cshl.org',-port=>2005) or die;
13 my $cosmid = Ace::Sequence->new(-seq=>'Y16B4A',
14 -db=>$db,-start=>-15000,-end=>15000) or die;
15 my @transcripts = $cosmid->transcripts;
17 my $panel = Ace::Graphics::Panel->new(
19 -segment => $cosmid,
20 -width => 800
21 );
22 $panel->add_track(arrow => $cosmid,
24 -bump => 0,
25 -tick=>2);
26 $panel->add_track(transcript => \@transcripts,
28 -fillcolor => 'wheat',
29 -fgcolor => 'black',
30 -key => 'Curated Genes',
31 -bump => +1,
32 -height => 10,
33 -label => 1);
34 my $boxes = $panel->boxes;
36 print $panel->png;
37
39 The Ace::Graphics::Panel class provides drawing and formatting services
40 for Ace::Sequence::Feature objects or Das::Segment::Feature objects.
41 Typically you will begin by creating a new Ace::Graphics::Panel object,
43 passing it the width of the visual display and the length of the seg‐
44 ment.
45 You will then call add_track() one or more times to add sets of related
47 features to the picture. When you have added all the features you
48 desire, you may call png() to convert the image into a PNG-format
49 image, or boxes() to return coordinate information that can be used to
50 create an imagemap.
51 Note that this modules depends on GD.
53
55 This section describes the class and object methods for Ace::Graph‐
56 ics::Panel.
57 CONSTRUCTORS
59 There is only one constructor, the new() method.
61 $panel = Ace::Graphics::Panel->new(@options)
63 The new() method creates a new panel object. The options are a set
64 of tag/value pairs as follows:
65 Option Value Default
67 ------ ----- -------
68 -length Length of sequence segment, in bp 0
70 -segment An Ace::Sequence or Das::Segment none
72 object, used to derive length if
73 not provided
74 -offset Base pair to place at extreme left $segment->start
76 of image.
77 -width Desired width of image, in pixels 600
79 -spacing Spacing between tracks, in pixels 5
81 -pad_top Additional whitespace between top 0
83 of image and contents, in pixels
84 -pad_bottom Additional whitespace between top 0
86 of image and bottom, in pixels
87 -pad_left Additional whitespace between left 0
89 of image and contents, in pixels
90 -pad_right Additional whitespace between right 0
92 of image and bottom, in pixels
93 -keycolor Background color for the key printed 'cornsilk'
95 at bottom of panel (if any)
96 -keyspacing Spacing between key glyphs in the 10
98 key printed at bottom of panel
99 (if any)
100 Typically you will pass new() an object that implements the
102 Bio::RangeI interface, providing a length() method, from which the
103 panel will derive its scale.
104 $panel = Ace::Graphics::Panel->new(-segment => $sequence,
106 -width => 800);
107 new() will return undef in case of an error. If the specified glyph
109 name is not a valid one, new() will throw an exception.
110 OBJECT METHODS
112 $track = $panel->add_track($glyph,$features,@options)
114 The add_track() method adds a new track to the image.
115 Tracks are horizontal bands which span the entire width of the
117 panel. Each track contains a number of graphical elements called
118 "glyphs", each corresponding to a sequence feature. There are dif‐
119 ferent glyph types, but each track can only contain a single type
120 of glyph. Options passed to the track control the color and size
121 of the glyphs, whether they are allowed to overlap, and other for‐
122 matting attributes. The height of a track is determined from its
123 contents and cannot be directly influenced.
124 The first two arguments are the glyph name and an array reference
126 containing the list of features to display. The order of the argu‐
127 ments is irrelevant, allowing either of these idioms:
128 $panel->add_track(arrow => \@features);
130 $panel->add_track(\@features => 'arrow');
131 The glyph name indicates how each feature is to be rendered. A
133 variety of glyphs are available, and the number is growing. Cur‐
134 rently, the following glyphs are available:
135 Name Description
137 ---- -----------
138 box A filled rectangle, nondirectional.
140 ellipse A filled ellipse, nondirectional.
142 arrow An arrow; can be unidirectional or bidirectional.
144 It is also capable of displaying a scale with
145 major and minor tickmarks, and can be oriented
146 horizontally or vertically.
147 segments A set of filled rectangles connected by solid lines.
149 Used for interrupted features, such as gapped
150 alignments.
151 transcript Similar to segments, but the connecting line is
153 a "hat" shape, and the direction of transcription
154 is indicated by a small arrow.
155 transcript2 Similar to transcript, but the arrow that indicates
157 the direction of transcription is the last exon
158 itself.
159 primers Two inward pointing arrows connected by a line.
161 Used for STSs.
162 toomany A "cloud", to indicate too many features to show
164 individually. This is a placeholder that will be
165 replaced by something more clever, such as a histogram
166 or density plot.
167 group A group of related features connected by a dashed line.
169 This is used internally by the Track class and should
170 not be called explicitly.
171 If the glyph name is omitted from add_track(), the "box" glyph will
173 be used by default.
174 The @options array is a list of name/value pairs that control the
176 attributes of the track. The options are in turn passed to the
177 glyphs. Each glyph has its own specialized subset of options, but
178 some are shared by all glyphs:
179 Option Description Default
181 ------ ----------- -------
182 -glyph Glyph to use none
184 -fgcolor Foreground color black
186 -outlinecolor black
188 Synonym for -fgcolor
189 -bgcolor Background color white
191 -fillcolor Interior color of filled turquoise
193 images
194 -linewidth Width of lines drawn by 1
196 glyph
197 -height Height of glyph 10
199 -font Glyph font gdSmallFont
201 -label Whether to draw a label false
203 -bump Bump direction 0
205 -connect_groups false
207 Connect groups by a
208 dashed line (see below)
209 -key Show this track in the undef
211 key
212 Colors can be expressed in either of two ways: as symbolic names
214 such as "cyan" and as HTML-style #RRGGBB triples. The symbolic
215 names are the 140 colors defined in the Netscape/Internet Explorer
216 color cube, and can be retrieved using the Ace::Graph‐
217 ics::Panel->color_names() method.
218 The background color is used for the background color of the track
220 itself. The foreground color controls the color of lines and
221 strings. The interior color is used for filled objects such as
222 boxes.
223 The -label argument controls whether or not the ID of the feature
225 should be printed next to the feature. It is accepted by most, but
226 not all of the glyphs.
227 The -bump argument controls what happens when glyphs collide. By
229 default, they will simply overlap (value 0). A -bump value of +1
230 will cause overlapping glyphs to bump downwards until there is room
231 for them. A -bump value of -1 will cause overlapping glyphs to
232 bump upwards.
233 The -key argument declares that the track is to be shown in a key
235 appended to the bottom of the image. The key contains a picture of
236 a glyph and a label describing what the glyph means. The label is
237 specified in the argument to -key.
238 If present, the -glyph argument overrides the glyph given in the
240 first or second argument.
241 add_track() returns an Ace::Graphics::Track object. You can use
243 this object to add additional features or to control the appearance
244 of the track with greater detail, or just ignore it. Tracks are
245 added in order from the top of the image to the bottom. To add
246 tracks to the top of the image, use unshift_track().
247 Typical usage is:
249 $panel->add_track( thistle => \@genes,
251 -fillcolor => 'green',
252 -fgcolor => 'black',
253 -bump => +1,
254 -height => 10,
255 -label => 1);
256 $track = unshift_track($glyph,$features,@options)
258 unshift_track() works like add_track(), except that the new track
259 is added to the top of the image rather than the bottom.
260 Adding groups of features: It is not uncommon to add a group of
262 features which are logically connected, such as the 5' and 3' ends
263 of EST reads. To group features into sets that remain on the same
264 horizontal position and bump together, pass the sets as an anony‐
265 mous array. To connect the groups by a dashed line, pass the -con‐
266 nect_groups argument with a true value. For example:
267 $panel->add_track(segments => [[$abc_5,$abc_3],
269 [$xxx_5,$xxx_3],
270 [$yyy_5,$yyy_3]],
271 -connect_groups => 1);
272 $gd = $panel->gd
274 The gd() method lays out the image and returns a GD::Image object
275 containing it. You may then call the GD::Image object's png() or
276 jpeg() methods to get the image data.
277 $png = $panel->png
279 The png() method returns the image as a PNG-format drawing, without
280 the intermediate step of returning a GD::Image object.
281 $boxes = $panel->boxes
283 @boxes = $panel->boxes
284 The boxes() method returns the coordinates of each glyph, useful
285 for constructing an image map. In a scalar context, boxes()
286 returns an array ref. In an list context, the method returns the
287 array directly.
288 Each member of the list is an anonymous array of the following for‐
290 mat:
291 [ $feature, $x1, $y1, $x2, $y2 ]
293 The first element is the feature object; either an
295 Ace::Sequence::Feature, a Das::Segment::Feature, or another Bioperl
296 Bio::SeqFeatureI object. The coordinates are the topleft and bot‐
297 tomright corners of the glyph, including any space allocated for
298 labels.
299 ACCESSORS
301 The following accessor methods provide access to various attributes of
303 the panel object. Called with no arguments, they each return the cur‐
304 rent value of the attribute. Called with a single argument, they set
305 the attribute and return its previous value.
306 Note that in most cases you must change attributes prior to invoking
308 gd(), png() or boxes(). These three methods all invoke an internal
309 layout() method which places the tracks and the glyphs within them, and
310 then caches the result.
311 Accessor Name Description
313 ------------- -----------
314 width() Get/set width of panel
316 spacing() Get/set spacing between tracks
317 length() Get/set length of segment (bp)
318 pad_top() Get/set top padding
319 pad_left() Get/set left padding
320 pad_bottom() Get/set bottom padding
321 pad_right() Get/set right padding
322 INTERNAL METHODS
324 The following methods are used internally, but may be useful for those
326 implementing new glyph types.
327 @names = Ace::Graphics::Panel->color_names
329 Return the symbolic names of the colors recognized by the panel
330 object. In a scalar context, returns an array reference.
331 @rgb = $panel->rgb($index)
333 Given a GD color index (between 0 and 140), returns the RGB triplet
334 corresponding to this index. This method is only useful within a
335 glyph's draw() routine, after the panel has allocated a GD::Image
336 and is populating it.
337 $index = $panel->translate($color)
339 Given a color, returns the GD::Image index. The color may be sym‐
340 bolic, such as "turquoise", or a #RRGGBB triple, as in #F0E0A8.
341 This method is only useful within a glyph's draw() routine, after
342 the panel has allocated a GD::Image and is populating it.
343 $panel->set_pen($width,$color)
345 Changes the width and color of the GD drawing pen to the values
346 indicated. This is called automatically by the GlyphFactory
347 fgcolor() method.
348
350 Please report them.
351
353 Ace::Sequence,Ace::Sequence::Feature, Ace::Graphics::Track,Ace::Graph‐
354 ics::Glyph, GD
355
357 Lincoln Stein <lstein@cshl.org>.
358 Copyright (c) 2001 Cold Spring Harbor Laboratory
360 This library is free software; you can redistribute it and/or modify it
362 under the same terms as Perl itself. See DISCLAIMER.txt for dis‐
363 claimers of warranty.
364perl v5.8.8 2001-02-20 Ace::Graphics::Panel(3)