1Ace::Graphics::Panel(3)User Contributed Perl DocumentatioAnce::Graphics::Panel(3)
2
3
4

NAME

6       Ace::Graphics::Panel - PNG graphics of Ace::Sequence::Feature objects
7

SYNOPSIS

9         use Ace::Sequence;
10         use Ace::Graphics::Panel;
11
12         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
16         my @transcripts = $cosmid->transcripts;
17
18         my $panel = Ace::Graphics::Panel->new(
19                                             -segment => $cosmid,
20                                             -width  => 800
21                                            );
22
23
24         $panel->add_track(arrow => $cosmid,
25                         -bump => 0,
26                         -tick=>2);
27
28         $panel->add_track(transcript => \@transcripts,
29                           -fillcolor =>  'wheat',
30                           -fgcolor   =>  'black',
31                           -key       => 'Curated Genes',
32                           -bump      =>  +1,
33                           -height    =>  10,
34                           -label     =>  1);
35
36         my $boxes = $panel->boxes;
37         print $panel->png;
38

DESCRIPTION

40       The Ace::Graphics::Panel class provides drawing and formatting services
41       for Ace::Sequence::Feature objects or Das::Segment::Feature objects.
42
43       Typically you will begin by creating a new Ace::Graphics::Panel object,
44       passing it the width of the visual display and the length of the
45       segment.
46
47       You will then call add_track() one or more times to add sets of related
48       features to the picture.  When you have added all the features you
49       desire, you may call png() to convert the image into a PNG-format
50       image, or boxes() to return coordinate information that can be used to
51       create an imagemap.
52
53       Note that this modules depends on GD.
54

METHODS

56       This section describes the class and object methods for
57       Ace::Graphics::Panel.
58
59   CONSTRUCTORS
60       There is only one constructor, the new() method.
61
62       $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
66             Option      Value                                Default
67             ------      -----                                -------
68
69             -length     Length of sequence segment, in bp    0
70
71             -segment    An Ace::Sequence or Das::Segment     none
72                         object, used to derive length if
73                         not provided
74
75             -offset     Base pair to place at extreme left   $segment->start
76                         of image.
77
78             -width      Desired width of image, in pixels    600
79
80             -spacing    Spacing between tracks, in pixels    5
81
82             -pad_top    Additional whitespace between top    0
83                         of image and contents, in pixels
84
85             -pad_bottom Additional whitespace between top    0
86                         of image and bottom, in pixels
87
88             -pad_left   Additional whitespace between left   0
89                         of image and contents, in pixels
90
91             -pad_right  Additional whitespace between right  0
92                         of image and bottom, in pixels
93
94             -keycolor   Background color for the key printed 'cornsilk'
95                         at bottom of panel (if any)
96
97             -keyspacing Spacing between key glyphs in the    10
98                         key printed at bottom of panel
99                         (if any)
100
101           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
105             $panel = Ace::Graphics::Panel->new(-segment => $sequence,
106                                                -width   => 800);
107
108           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
111   OBJECT METHODS
112       $track = $panel->add_track($glyph,$features,@options)
113           The add_track() method adds a new track to the image.
114
115           Tracks are horizontal bands which span the entire width of the
116           panel.  Each track contains a number of graphical elements called
117           "glyphs", each corresponding to a sequence feature. There are
118           different glyph types, but each track can only contain a single
119           type of glyph.  Options passed to the track control the color and
120           size of the glyphs, whether they are allowed to overlap, and other
121           formatting attributes.  The height of a track is determined from
122           its contents and cannot be directly influenced.
123
124           The first two arguments are the glyph name and an array reference
125           containing the list of features to display.  The order of the
126           arguments is irrelevant, allowing either of these idioms:
127
128             $panel->add_track(arrow => \@features);
129             $panel->add_track(\@features => 'arrow');
130
131           The glyph name indicates how each feature is to be rendered.  A
132           variety of glyphs are available, and the number is growing.
133           Currently, the following glyphs are available:
134
135             Name        Description
136             ----        -----------
137
138             box         A filled rectangle, nondirectional.
139
140             ellipse     A filled ellipse, nondirectional.
141
142             arrow       An arrow; can be unidirectional or bidirectional.
143                         It is also capable of displaying a scale with
144                         major and minor tickmarks, and can be oriented
145                         horizontally or vertically.
146
147             segments    A set of filled rectangles connected by solid lines.
148                         Used for interrupted features, such as gapped
149                         alignments.
150
151             transcript  Similar to segments, but the connecting line is
152                         a "hat" shape, and the direction of transcription
153                         is indicated by a small arrow.
154
155             transcript2 Similar to transcript, but the arrow that indicates
156                         the direction of transcription is the last exon
157                         itself.
158
159             primers     Two inward pointing arrows connected by a line.
160                         Used for STSs.
161
162             toomany     A "cloud", to indicate too many features to show
163                         individually.  This is a placeholder that will be
164                         replaced by something more clever, such as a histogram
165                         or density plot.
166
167             group       A group of related features connected by a dashed line.
168                         This is used internally by the Track class and should
169                         not be called explicitly.
170
171           If the glyph name is omitted from add_track(), the "box" glyph will
172           be used by default.
173
174           The @options array is a list of name/value pairs that control the
175           attributes of the track.  The options are in turn passed to the
176           glyphs.  Each glyph has its own specialized subset of options, but
177           some are shared by all glyphs:
178
179             Option      Description               Default
180             ------      -----------               -------
181
182             -glyph      Glyph to use              none
183
184             -fgcolor    Foreground color          black
185
186             -outlinecolor                         black
187                         Synonym for -fgcolor
188
189             -bgcolor    Background color          white
190
191             -fillcolor  Interior color of filled  turquoise
192                         images
193
194             -linewidth  Width of lines drawn by   1
195                               glyph
196
197             -height     Height of glyph           10
198
199             -font       Glyph font                gdSmallFont
200
201             -label      Whether to draw a label   false
202
203             -bump       Bump direction            0
204
205             -connect_groups                       false
206                         Connect groups by a
207                         dashed line (see below)
208
209             -key        Show this track in the    undef
210                         key
211
212           Colors can be expressed in either of two ways: as symbolic names
213           such as "cyan" and as HTML-style #RRGGBB triples.  The symbolic
214           names are the 140 colors defined in the Netscape/Internet Explorer
215           color cube, and can be retrieved using the
216           Ace::Graphics::Panel->color_names() method.
217
218           The background color is used for the background color of the track
219           itself.  The foreground color controls the color of lines and
220           strings.  The interior color is used for filled objects such as
221           boxes.
222
223           The -label argument controls whether or not the ID of the feature
224           should be printed next to the feature.  It is accepted by most, but
225           not all of the glyphs.
226
227           The -bump argument controls what happens when glyphs collide.  By
228           default, they will simply overlap (value 0).  A -bump value of +1
229           will cause overlapping glyphs to bump downwards until there is room
230           for them.  A -bump value of -1 will cause overlapping glyphs to
231           bump upwards.
232
233           The -key argument declares that the track is to be shown in a key
234           appended to the bottom of the image.  The key contains a picture of
235           a glyph and a label describing what the glyph means.  The label is
236           specified in the argument to -key.
237
238           If present, the -glyph argument overrides the glyph given in the
239           first or second argument.
240
241           add_track() returns an Ace::Graphics::Track object.  You can use
242           this object to add additional features or to control the appearance
243           of the track with greater detail, or just ignore it.  Tracks are
244           added in order from the top of the image to the bottom.  To add
245           tracks to the top of the image, use unshift_track().
246
247           Typical usage is:
248
249            $panel->add_track( thistle    => \@genes,
250                               -fillcolor =>  'green',
251                               -fgcolor   =>  'black',
252                               -bump      =>  +1,
253                               -height    => 10,
254                               -label     => 1);
255
256       $track = unshift_track($glyph,$features,@options)
257           unshift_track() works like add_track(), except that the new track
258           is added to the top of the image rather than the bottom.
259
260           Adding groups of features: It is not uncommon to add a group of
261           features which are logically connected, such as the 5' and 3' ends
262           of EST reads.  To group features into sets that remain on the same
263           horizontal position and bump together, pass the sets as an
264           anonymous array.  To connect the groups by a dashed line, pass the
265           -connect_groups argument with a true value.  For example:
266
267             $panel->add_track(segments => [[$abc_5,$abc_3],
268                                            [$xxx_5,$xxx_3],
269                                            [$yyy_5,$yyy_3]],
270                               -connect_groups => 1);
271
272       $gd = $panel->gd
273           The gd() method lays out the image and returns a GD::Image object
274           containing it.  You may then call the GD::Image object's png() or
275           jpeg() methods to get the image data.
276
277       $png = $panel->png
278           The png() method returns the image as a PNG-format drawing, without
279           the intermediate step of returning a GD::Image object.
280
281       $boxes = $panel->boxes
282       @boxes = $panel->boxes
283           The boxes() method returns the coordinates of each glyph, useful
284           for constructing an image map.  In a scalar context, boxes()
285           returns an array ref.  In an list context, the method returns the
286           array directly.
287
288           Each member of the list is an anonymous array of the following
289           format:
290
291             [ $feature, $x1, $y1, $x2, $y2 ]
292
293           The first element is the feature object; either an
294           Ace::Sequence::Feature, a Das::Segment::Feature, or another Bioperl
295           Bio::SeqFeatureI object.  The coordinates are the topleft and
296           bottomright corners of the glyph, including any space allocated for
297           labels.
298
299   ACCESSORS
300       The following accessor methods provide access to various attributes of
301       the panel object.  Called with no arguments, they each return the
302       current value of the attribute.  Called with a single argument, they
303       set the attribute and return its previous value.
304
305       Note that in most cases you must change attributes prior to invoking
306       gd(), png() or boxes().  These three methods all invoke an internal
307       layout() method which places the tracks and the glyphs within them, and
308       then caches the result.
309
310          Accessor Name      Description
311          -------------      -----------
312
313          width()            Get/set width of panel
314          spacing()          Get/set spacing between tracks
315          length()           Get/set length of segment (bp)
316          pad_top()          Get/set top padding
317          pad_left()         Get/set left padding
318          pad_bottom()       Get/set bottom padding
319          pad_right()        Get/set right padding
320
321   INTERNAL METHODS
322       The following methods are used internally, but may be useful for those
323       implementing new glyph types.
324
325       @names = Ace::Graphics::Panel->color_names
326           Return the symbolic names of the colors recognized by the panel
327           object.  In a scalar context, returns an array reference.
328
329       @rgb = $panel->rgb($index)
330           Given a GD color index (between 0 and 140), returns the RGB triplet
331           corresponding to this index.  This method is only useful within a
332           glyph's draw() routine, after the panel has allocated a GD::Image
333           and is populating it.
334
335       $index = $panel->translate($color)
336           Given a color, returns the GD::Image index.  The color may be
337           symbolic, such as "turquoise", or a #RRGGBB triple, as in #F0E0A8.
338           This method is only useful within a glyph's draw() routine, after
339           the panel has allocated a GD::Image and is populating it.
340
341       $panel->set_pen($width,$color)
342           Changes the width and color of the GD drawing pen to the values
343           indicated.  This is called automatically by the GlyphFactory
344           fgcolor() method.
345

BUGS

347       Please report them.
348

SEE ALSO

350       Ace::Sequence,Ace::Sequence::Feature,
351       Ace::Graphics::Track,Ace::Graphics::Glyph, GD
352

AUTHOR

354       Lincoln Stein <lstein@cshl.org>.
355
356       Copyright (c) 2001 Cold Spring Harbor Laboratory
357
358       This library is free software; you can redistribute it and/or modify it
359       under the same terms as Perl itself.  See DISCLAIMER.txt for
360       disclaimers of warranty.
361
362
363
364perl v5.34.0                      2022-01-20           Ace::Graphics::Panel(3)
Impressum