Ace::G...:Panel(3pm)

📦
version 1.92 · 8 versions
, in ubuntu stonking

💖 Ace::Graphics::Panel 💖

okay bestie, buckle up, because this is Ace::Graphics::Panel(3pm) from the User Contributed Perl Documentation corner of the universe, and it is giving beautiful little pictures of your sequence features. 🎀

🦋 NAME 🦋

Ace::Graphics::Panel — PNG graphics of Ace::Sequence::Feature objects. no cap, it draws the features. 🖼️✨

🌸 SYNOPSIS 🌸

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;

fr fr, that's the whole vibe in one snippet. 💅

🫶 DESCRIPTION 🫶

The Ace::Graphics::Panel class is the one that handles all the drawing and formatting services for Ace::Sequence::Feature objects and Das::Segment::Feature objects. both. she contains multitudes. 😌

Usually you start by making a brand new Ace::Graphics::Panel object, and you hand it the width of the visual display plus the length of the segment. that's your blank canvas, bestie. 🎨

Then you call add_track() one or more times to stack sets of related features onto the picture. when you're done adding everything your heart desires, you can call png() to turn the image into an actual PNG-format image, or you can call boxes() to get back coordinate info that you can use to build an imagemap. 🔥

lowkey important: this modules depends on GD. she will NOT run without GD. periodt. 🚨

✨ METHODS ✨

This section describes the class and object methods for Ace::Graphics::Panel. let's get into it. 💜

🎀 CONSTRUCTORS 🎀

There is only one constructor, the new() method. one icon, no understudies. 👑

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

The new() method creates a new panel object. The options are a set of tag/value pairs, and here they are in all their glory:

  • -length — length of the sequence segment, in bp. Defaults to 0.
  • -segment — an Ace::Sequence or Das::Segment object, used to derive the length if you didn't provide one. Defaults to none (as in, nope, nothing).
  • -offset — the base pair to place at the extreme left of the image. Defaults to $segment->start.
  • -width — desired width of the image, in pixels. Defaults to 600.
  • -spacing — spacing between tracks, in pixels. Defaults to 5.
  • -pad_top — extra whitespace between the top of the image and the contents, in pixels. Defaults to 0.
  • -pad_bottom — extra whitespace between the image and its contents at the bottom, in pixels. Defaults to 0.
  • -pad_left — extra whitespace between the left of the image and the contents, in pixels. Defaults to 0.
  • -pad_right — extra whitespace between the right of the image and its contents, in pixels. Defaults to 0.
  • -keycolor — background color for the key that gets printed at the bottom of the panel (if there is one). Defaults to 'cornsilk'.
  • -keyspacing — spacing between the key glyphs in the key printed at the bottom of the panel (if there is one). Defaults to 10.

Typically you'll pass new() an object that implements the Bio::RangeI interface, meaning it provides a length() method — the panel derives its scale from that. 🧚

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

Now the part you need to know: new() will return undef if there's an error. but if the glyph name you specified is not a valid one, new() will straight up throw an exception. 💀 so double check your spelling, bestie.

🌈 OBJECT METHODS 🌈

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

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

Tracks are horizontal bands that span the entire width of the panel. Each track holds a bunch of graphical elements called "glyphs", and each glyph corresponds to a sequence feature. There are different glyph types, but here's the rule: each track can only contain a single type of glyph. no mixing, that's the law. 😤 Options you pass to the track control the color and size of the glyphs, whether they're allowed to overlap, and other formatting stuff. And the height of a track? That's determined from its contents — you can't directly influence it. she decides her own height. 💅

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, so both of these idioms are totally valid:

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

The glyph name tells the panel how each feature should be rendered. A whole variety of glyphs are available and the number keeps growing. Currently, these are the ones:

  • box — a filled rectangle, nondirectional. simple. classic. 🎁
  • ellipse — a filled ellipse, nondirectional. 🥚
  • arrow — an arrow, and it can be unidirectional or bidirectional. It can also display a scale with major and minor tickmarks, and it can be oriented horizontally or vertically. multi-talented fr. 🏹
  • segments — a set of filled rectangles connected by solid lines. Used for interrupted features, like 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. iconic behavior. 👑
  • primers — two inward pointing arrows connected by a line. Used for STSs. 📍
  • toomany — a "cloud", to indicate there are too many features to show individually. This one 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. don't touch it, it's not for you bestie. 🚫

If you omit the glyph name 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, and those options get passed along to the glyphs. Each glyph has its own specialized subset of options, but some are shared by all glyphs:

  • -glyph — glyph to use. Defaults to none.
  • -fgcolor — foreground color. Defaults to black.
  • -outlinecolor — synonym for -fgcolor. Defaults to black.
  • -bgcolor — background color. Defaults to white.
  • -fillcolor — interior color of filled images. Defaults to turquoise.
  • -linewidth — width of lines drawn by the glyph. Defaults to 1.
  • -height — height of the glyph. Defaults to 10.
  • -font — glyph font. Defaults to gdSmallFont.
  • -label — whether to draw a label. Defaults to false.
  • -bump — bump direction. Defaults to 0.
  • -connect_groups — connect groups by a dashed line (see below). Defaults to false.
  • -key — show this track in the key. Defaults to undef.

Okay so colors: you can express them in either of two ways — as symbolic names like "cyan", or as HTML-style #RRGGBB triples. The symbolic names are the 140 colors defined in the Netscape/Internet Explorer color cube, and you can retrieve them using the Ace::Graphics::Panel->color_names() method. 🌈

Here's which color does what: 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. she's organized, she has a system. 💅

The -label argument controls whether or not the ID of the feature gets printed next to the feature. It's accepted by most, but not all, of the glyphs. 😭

The -bump argument controls what happens when glyphs collide. By default they just overlap (value 0). A -bump value of +1 will cause overlapping glyphs to bump downwards until there's room for them. A -bump value of -1 will cause overlapping glyphs to bump upwards. ⬆️⬇️

The -key argument declares that the track should be shown in a key appended to the bottom of the image. The key contains a picture of a glyph plus a label describing what that glyph means — and that label is whatever you specify in the argument to -key. 🏷️

If present, the -glyph argument overrides the glyph given in the first or second argument. she said overrule. 👀

add_track() returns an Ace::Graphics::Track object. You can use that object to add more features, or to control the appearance of the track in greater detail, or honestly just ignore it entirely. Tracks get added in order from the top of the image to the bottom. And if you want to add tracks to the top of the image instead, use unshift_track(). ✨

Typical usage looks like this:

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

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

unshift_track() works exactly like add_track(), with one difference: the new track gets 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 that are logically connected, like the 5' and 3' ends of EST reads. To group features into sets that stay at the same horizontal position and bump together, pass the sets as an anonymous array. And to connect those groups with 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 can then call that GD::Image object's png() or jpeg() methods to get the actual image data. 🖼️✨

  • $png = $panel->png — hands you back the image as a PNG-format drawing, skipping the whole ~intermediate step~ of giving you a GD::Image object first. straight to the goods, no middleman 💅
  • $boxes = $panel->boxes
  • @boxes = $panel->boxes — the boxes() method gives you the coordinates of every single glyph, which is literally the move when you're building an image map 🗺️✨ In a scalar context it hands back an array ref. In a list context it just gives you the array directly, no wrapper, no drama.

Every member of that list is an anonymous array looking exactly like this:

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

First element = the feature object; and that's 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, and yes bestie that includes any space set aside for labels 🏷️🫶

🌸 ACCESSORS 🌸

These accessor methods are your little backstage passes to the panel object's attributes 🎀 Called with no arguments, each one returns the current value of that attribute. Called with a single argument, it sets the attribute and returns the previous value (so sneaky, so useful).

⚠️ okay important: in most cases you must change attributes before you call gd(), png() or boxes(). All three of those invoke an internal layout() method that places the tracks and the glyphs inside them, and then caches the result. Change stuff after and, well… it's cooked 🔥
  • 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

🧚 INTERNAL METHODS 🧚

These are used internally, but if you're out here implementing new glyph types they might just be your new besties 💜

  • @names = Ace::Graphics::Panel->color_names — returns the symbolic names of all the colors the panel object recognizes. In a scalar context, returns an array reference instead 🌈
  • @rgb = $panel->rgb($index) — give it a GD color index (between 0 and 140) and it returns the RGB triplet for that index. Heads up: this is only useful inside a glyph's draw() routine, once the panel has allocated a GD::Image and is populating it 🌸
  • $index = $panel->translate($color) — give it a color and it returns the GD::Image index. The color can be symbolic, like "turquoise", or a #RRGGBB triple, like #F0E0A8. Same deal as above: only useful inside 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 whatever values you pass in. This gets called automatically by the GlyphFactory fgcolor() method, so you don't gotta 🖊️✨

💀 BUGS 💀

Please report them. that's it. that's the whole section. please report them bestie 🙈

👑 SEE ALSO 👑

Ace::Sequence, Ace::Sequence::Feature, Ace::Graphics::Track, Ace::Graphics::Glyph, 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.

and that's the whole page, bestie, we did it 🎉 this was perl v5.42.3, dated 2026-08-19 — go forth and draw some iconic panels, no cap 💅🦋✨

📦 where this page comes from