Bio::G...:Glyph(3pm)

📦

version 2.40 · 2 versions

2.40 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
2.40 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

okay bestie, this is the manual page for Bio::G...:Glyph(3pm) from User Contributed Perl Documentation. Part 1, so no sign-off — just vibes, facts, and zero skipped details. ✨

💖 NAME 💖

Bio::Graphics::Glyph — Base class for Bio::Graphics::Glyph objects

🌸 SYNOPSIS 🌸

See Bio::Graphics::Panel.

🦋 DESCRIPTION 🦋

Okay so Bio::Graphics::Glyph is the base class for all glyph objects. Each glyph is a wrapper around an Bio:SeqFeatureI object, knows how to render itself on an Bio::Graphics::Panel, and has a variety of configuration variables. 💅

End developers will not ordinarily work directly with Bio::Graphics::Glyph objects, but with Bio::Graphics::Glyph::generic and its subclasses. Similarly, most glyph developers will want to subclass from Bio::Graphics::Glyph::generic because the latter provides labeling and arrow-drawing facilities. Slay. ✨

🎀 METHODS 🎀

This section describes the class and object methods for Bio::Graphics::Glyph.

🧸 CONSTRUCTORS 🧸

Bio::Graphics::Glyph objects are constructed automatically by an Bio::Graphics::Glyph::Factory, and are not usually created by end-developer code. No cap.

$glyph = Bio::Graphics::Glyph->new(-feature=>$feature,-factory=>$factory)

Given a sequence feature, creates an Bio::Graphics::Glyph object to display it. The -feature argument points to the Bio:SeqFeatureI object to display, and -factory indicates an Bio::Graphics::Glyph::Factory object from which the glyph will fetch all its run-time configuration information. Factories are created and manipulated by the Bio::Graphics::Panel object.

A standard set of options are recognized. See OPTIONS.

💫 OBJECT METHODS 💫

Once a glyph is created, it responds to a large number of methods. In this section, these methods are grouped into related categories. Main character energy, honestly. 💖

🔍 Retrieving glyph context:

$factory = $glyph->factory — Get the Bio::Graphics::Glyph::Factory associated with this object. This cannot be changed once it is set. Periodt.
$panel = $glyph->panel — Get the Bio::Graphics::Panel associated with this object. This cannot be changed once it is set.
$feature = $glyph->feature — Get the sequence feature associated with this object. This cannot be changed once it is set.
$feature = $glyph->parent_feature() — Within callbacks only, the parent_feature() method returns the parent of the current feature, if there is one. Called with a numeric argument, ascends the parentage tree: parent_feature(1) will return the parent, parent_feature(2) will return the grandparent, etc. If there is no parent, returns undef.
$feature = $glyph->add_feature(@features) — Add the list of features to the glyph, creating subparts. This is most common done with the track glyph returned by Bio::Graphics::Panel->add_track().

If the Bio::Graphics::Panel was initialized with -feature_limit set to a non-zero value, then calls to a track glyph's add_feature() method will maintain a count of features added to the track. Once the feature count exceeds the value set in -feature_limit, additional features will displace existing ones in a way that effects a uniform sampling of the total feature set. This is useful to protect against excessively large tracks. The total number of features added can be retrieved by calling the glyph's feature_count() method.

$feature = $glyph->add_group(@features) — This is similar to add_feature(), but the list of features is treated as a group and can be configured as a set.
$glyph->finished — When you are finished with a glyph, you can call its finished() method in order to break cycles that would otherwise cause memory leaks. finished() is typically only used by the Panel object.

bestie, ignoring finished() is how you get memory leaks. It's giving haunted house. 💀

$subglyph = $glyph->make_subglyph($level,@sub_features) — This method is called to create subglyphs from a list of subfeatures. The $level indicates the current level of the glyph (top-level glyphs are level 0, subglyphs are level 1, etc).

Ordinarily this method simply calls $self->factory->make_subglyph($level,@sub_features). Override it in subclasses to create subglyphs of a particular type. For example:

          sub make_subglyph {
             my $self = shift;
             my $level = shift;
             my $factory = $self->factory;
             $factory->make_glyph($factory,'arrow',@_);
          }

$count = $glyph->feature_count() — Return the number of features added to this glyph via add_feature().
$flag = $glyph->features_clipped() — If the panel was initialized with -feature_limit set to a non-zero value, then calls to add_features() will limit the number of glyphs to the indicated value. If this value was exceeded, then features_clipped() will return true.

🎨 Retrieving glyph options:

$fgcolor = $glyph->fgcolor
$bgcolor = $glyph->bgcolor
$fontcolor = $glyph->fontcolor
$fontcolor = $glyph->font2color
$fillcolor = $glyph->fillcolor

These methods return the configured foreground, background, font, alternative font, and fill colors for the glyph in the form of a GD::Image color index. 🎨

$color = $glyph->tkcolor — This method returns a color to be used to flood-fill the entire glyph before drawing (currently used by the "track" glyph). 👑
($left,$top,$right,$bottom) = $glyph->bounds($dx,$dy) — Given the topleft coordinates of the glyph, return the bounding box of its contents, exclusive of padding. This is typically called by the draw() and draw_component() methods to recover the position of the glyph.
($left,$top,$right,$bottom) = $glyph->calculate_boundaries($dx,$dy) — An alias for bounds(), used by some glyphs for compatibility with older versions of this module.
$width = $glyph->width([$newwidth]) — Return the width of the glyph, not including left or right padding. This is ordinarily set internally based on the size of the feature and the scale of the panel.
$width = $glyph->layout_width — Returns the width of the glyph including left and right padding.
$width = $glyph->height — Returns the height of the glyph, not including the top or bottom padding. This is calculated from the "height" option and cannot be changed.
$font = $glyph->font — Return the font for the glyph.
$option = $glyph->option($option) — Return the value of the indicated option.
$index = $glyph->color($option_name) — Given an option name that corresponds to a color (e.g. 'fgcolor') look up the option and translate it into a GD color index.
$index = $glyph->translate_color($color) — Given a symbolic or #RRGGBB-form color name, returns its GD index.
$level = $glyph->level — The "level" is the nesting level of the glyph. Groups are level -1, top level glyphs are level 0, subparts (e.g. exons) are level 1 and so forth.
@parts = $glyph->parts — For glyphs that can contain subparts (e.g. the segments glyph), this method will return the list of subglyphs it contains. Subglyphs are created automatically by the new() method and are created subject to the maximum recursion depth specified by the maxdepth() method and/or the -maxdepth option.

⚙️ Setting an option:

$glyph->configure(-name=>$value) — You may change a glyph option after it is created using set_option(). This is most commonly used to configure track glyphs.

🧬 Retrieving information about the sequence:

$start = $glyph->start
$end = $glyph->end

These methods return the start and end of the glyph in base pair units.

$offset = $glyph->offset — Returns the offset of the segment (the base pair at the far left of the image).
$length = $glyph->length — Returns the length of the sequence segment.

📐 Retrieving formatting information:

$top = $glyph->top
$left = $glyph->left
$bottom = $glyph->bottom
$right = $glyph->right

These methods return the top, left, bottom and right of the glyph in pixel coordinates.

$height = $glyph->height — Returns the height of the glyph. This may be somewhat larger or smaller than the height suggested by the GlyphFactory, depending on the type of the glyph.
$scale = $glyph->scale — Get the scale for the glyph in pixels/bp.
$height = $glyph->labelheight — Return the height of the label, if any.
$label = $glyph->label — Return a human-readable label for the glyph.

These methods are called by Bio::Graphics::Track during the layout process:

$glyph->move($dx,$dy) — Move the glyph in pixel coordinates by the indicated delta-x and delta-y values.
($x1,$y1,$x2,$y2) = $glyph->box — Return the current position of the glyph.

These methods are intended to be overridden in subclasses:

$glyph->calculate_height — Calculate the height of the glyph.
$glyph->calculate_left — Calculate the left side of the glyph.
$glyph->calculate_right — Calculate the right side of the glyph.
$glyph->draw($gd,$left,$top) — Optionally offset the glyph by the indicated amount and draw it onto the GD::Image object.
$glyph->draw_label($gd,$left,$top) — Draw the label for the glyph onto the provided GD::Image object, optionally offsetting by the amounts indicated in $left and $right.
$glyph->maxdepth() — This returns the maximum number of levels of feature subparts that the glyph will recurse through. For example, returning 0 indicates that the glyph will only draw the top-level feature. Returning 1 indicates that it will only draw the top-level feature and one level of subfeatures. Returning 2 will descend down two levels. Overriding this method will speed up rendering by avoiding creating of a bunch of subglyphs that will never be drawn.

The default behavior is to return undef (unlimited levels of descent) unless the -maxdepth option is passed, in which case this number is returned.

Note that Bio::Graphics::Glyph::generic overrides maxdepth() to return 0, meaning no descent into subparts will be performed.

These methods are useful utility routines:

@pixels = $glyph->map_pt(@bases); — Map the list of base position, given in base pair units, into pixels, using the current scale and glyph position. This method will accept a single base position or an array.
$glyph->filled_box($gd,$x1,$y1,$x2,$y2) — Draw a filled rectangle with the appropriate foreground and fill colors, and pen width onto the GD::Image object given by $gd, using the provided rectangle coordinates.
$glyph->filled_oval($gd,$x1,$y1,$x2,$y2) — As above, but draws an oval inscribed on the rectangle.
$glyph->exceeds_depth — Returns true if descending into another level of subfeatures will exceed the value returned by maxdepth().

✨ OPTIONS ✨

okay bestie, these options are the standard ones every Glyph gets 💅 — like the shared starter pack. For extra options, go peek at the individual glyph pages, mmkay?

also!! there's a lil script called glyph_help.pl that literally tries to document each glyph's shared and specific options, and gives you a whole interface to graphically inspect what different options actually do. iconic of it tbh 🎀

  Option      Description                      Default
  ------      -----------                      -------

  -fgcolor      Foreground color               black

  -bgcolor      Background color               turquoise

  -fillcolor    Synonym for -bgcolor

  -linewidth    Line width                     1

  -height       Height of glyph                10

  -font         Glyph font                     gdSmallFont

  -connector    Connector type                 undef (false)

  -connector_color
                Connector color                black

  -strand_arrow Whether to indicate            undef (false)
                 strandedness

  -stranded     Whether to indicate            undef (false)
                 strandedness
                 (same as above))

  -label        Whether to draw a label        undef (false)

  -description  Whether to draw a description  undef (false)

  -no_subparts  Set to true to prevent         undef (false)
                drawing of the subparts
                of a feature.

  -ignore_sub_part Give the types/methods of   undef
                subparts to ignore (as a
                space delimited list).

  -maxdepth     Specifies the maximum number   undef (unlimited)
                child-generations to decend
                when getting subfeatures

  -sort_order   Specify layout sort order      "default"

  -always_sort  Sort even when bumping is off  undef (false)

  -bump_limit   Maximum number of levels to bump undef (unlimited)

  -hilite       Highlight color                undef (no color)

  -link, -title, -target
                These options are used when creating imagemaps
                for display on the web.  See L<Bio::Graphics::Panel/"Creating Imagemaps">.

🔗 the connector tea

so when a glyph is made of multiple segments, the -connector option decides what gets drawn between them. default is undef, which means no connector at all, sorry. but you got options, bestie:

   "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.
   "crossed" a straight horizontal connector with an "X" on it
              (Can be used when segments are not yet validated
               by some internal experiments...)

and -connector_color sets the color of that connector, if there is one. slay 🌈

🏷️ labels & descriptions

the label gets printed above the glyph. you can hand -label an anonymous subroutine, and it'll get called with the feature as its single argument — you're expected to return the string to use as the label. 💖

if you give -label the numeric value 1, the label gets read off the feature's seqname(), and info() and primary_tag() methods get called until a suitable name turns up. and heads up: if you want a label that literally says "1", pass the string "1 " — that's a 1 followed by a space, okay? 🙈

the description prints below the glyph. same deal — pass -description an anonymous subroutine and it gets the feature as its single argument, expected to return the string for the description. if you hand -description the numeric value 1, the description is read off the feature's source_tag() method. and again, to get a description that just says "1", pass the string "1 " (one, then a space). ✨

and for ACEDB Ace::Sequence feature objects specifically? the feature's info(), Brief_identification() and Locus() methods get called to build a suitable description. 💅

➡️ strand_arrow

-strand_arrow, if it's true, asks the glyph to show which strand it's on — usually by drawing an arrowhead. but ngl, not every glyph will respond to this request, so don't be shocked. for historical reasons, -stranded is a synonym for this option (yes, the manpage really did just say "same as above))." we love legacy code 🫶).

for multisegmented features: an arrowhead gets drawn on each component — unless you give -strand_arrow a value of "ends". in that case only the rightmost component gets arrowheads (for + strand features), or only the leftmost component (for - strand features). periodt.

🔀 sort_order

by default, features get drawn with a layout based purely on position, which assures maximal "packing" of the glyphs when bumped. but sometimes you wanna sort by score or some other comparison instead — like when more "important" features should sit nearer the top, stacked above the less important ones. 👑

-sort_order gives you a few built-in values to shake up the default sort order (which is by "left" position):

"low_score" (or "high_score") — sorts features from lowest to highest score, or vice versa
"left" (or "default") and "right" — sorts features by their position in the sequence
"longest" (or "shortest") — sorts the longest (or shortest) features first
"strand" — sorts by strand: "+1" (forward), then "0" (unknown, or NA), then "-1" (reverse)
"name" — sorts by the display_name of the features

in all cases, the "left" position breaks any ties. and if you wanna break ties with a different field, you can string options together with a "|" character — like "strand|low_score|right", which sorts first by strand, then score (lowest to highest), then by "right" position in the sequence. cute, right? 🦋

finally, you can hand it a subroutine coderef with a $$ prototype. it receives two glyphs as arguments and should return -1, 0 or 1 (check Perl's sort() function if you need the deets). 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 "start" position breaking any ties):

  sort_order = sub ($$) {
    my ($glyph1,$glyph2) = @_;
    my $a = $glyph1->feature;
    my $b = $glyph2->feature;
    ( $b->score/log($b->length)
          <=>
      $a->score/log($a->length) )
          ||
    ( $a->start <=> $b->start )
  }

🚨 bestie, listen: it is important to remember to use the $$ prototype exactly as shown in the example. otherwise Bio::Graphics will quit with an exception. no cap.

the arguments are subclasses of Bio::Graphics::Glyph, not the features themselves. glyphs implement some — but not all — of the feature methods, so to be safe, call the two glyphs' feature() methods to convert them into the actual features. 🧚

🔁 always_sort

-always_sort, if true, sorts features even if bumping is turned off. this is useful when you want overlapping features to stack in a particular order. features towards the end of the list will overlay those towards the beginning of the sort order. the way that works... lowkey important. 💜

🖍️ hilite

-hilite draws a colored box behind each feature using the color you indicate. typically you pass it a code ref that returns a color name. like so:

  -hilite => sub { my $name = shift->display_name;
                   return 'yellow' if $name =~ /XYZ/ }

🚫 no_subparts

-no_subparts stops the glyph from searching its feature for subfeatures. this may boost performance if you already know none of your features contain subfeatures. efficiency queen behavior 💅

🌸 SUBCLASSING Bio::Graphics::Glyph 🌸

by convention, subclasses are all lower-case. start each subclass with a preamble like this one:

 package Bio::Graphics::Glyph::crossbox;

 use strict;
 use base qw(Bio::Graphics::Glyph);

then override the methods you actually need. typically, just the draw() method needs overriding. but if you need extra room in the glyph, you can override calculate_height(), calculate_left() and calculate_right(). and bestie, do NOT directly override height(), left() and right() — their whole job is caching the values returned by their calculating cousins so you don't do time-consuming recalculation over and over. respect the cache 🙏

a simple draw() method looks like this:

 sub draw {
  my $self = shift;
  $self->SUPER::draw(@_);
  my $gd = shift;

  # and draw a cross through the box
  my ($x1,$y1,$x2,$y2) = $self->calculate_boundaries(@_);
  my $fg = $self->fgcolor;
  $gd->line($x1,$y1,$x2,$y2,$fg);
  $gd->line($x1,$y2,$x2,$y1,$fg);
 }

this subclass draws a simple box with two lines criss-crossed through it. we first call our inherited draw() method to generate the filled box and label. then we call calculate_boundaries() to get the coordinates of the glyph, ignoring any extra space taken up by labels. we call fgcolor() to get the desired foreground color, and then call $gd->line() twice to generate the criss-cross. chef's kiss 🎀

for more complex draw() methods, go look at Bio::Graphics::Glyph::transcript and Bio::Graphics::Glyph::segments. 🌟

alsooo, please avoid using a specific image class (like via use GD) inside your glyph package. instead, rely on the image package passed to the draw() method. this approach lets supported image classes expand in the future without you having to redesign your glyph. if you need access to specific image classes like Polygon, Image, or Font, generate them like this:

 sub draw {
  my $self = shift;
  my $image_class = shift;

  my $polygon_package = $self->polygon_package->new()
  ...
  }

💀 BUGS 💀

Please report them.

(that's it. that's the whole section. short king energy fr fr 😭)

🌈 SEE ALSO 🌈

okay bestie, here's the whole squad 💖 this is the extended universe, the group chat, the entire guest list. go read these when you're done here, no cap:

Bio::DB::GFF::Feature
Ace::Sequence
Bio::Graphics::Panel
Bio::Graphics::Track
Bio::Graphics::Glyph::Factory
Bio::Graphics::Glyph::alignment
Bio::Graphics::Glyph::anchored_arrow
Bio::Graphics::Glyph::arrow
Bio::Graphics::Glyph::box
Bio::Graphics::Glyph::broken_line
Bio::Graphics::Glyph::cds
Bio::Graphics::Glyph::christmas_arrow
Bio::Graphics::Glyph::crossbox
Bio::Graphics::Glyph::dashed_line
Bio::Graphics::Glyph::diamond
Bio::Graphics::Glyph::dna
Bio::Graphics::Glyph::dot
Bio::Graphics::Glyph::dumbbell
Bio::Graphics::Glyph::ellipse
Bio::Graphics::Glyph::ex
Bio::Graphics::Glyph::extending_arrow
Bio::Graphics::Glyph::flag
Bio::Graphics::Glyph::gene
Bio::Graphics::Glyph::generic
Bio::Graphics::Glyph::graded_segments
Bio::Graphics::Glyph::group
Bio::Graphics::Glyph::heterogeneous_segments
Bio::Graphics::Glyph::image
Bio::Graphics::Glyph::lightning
Bio::Graphics::Glyph::line
Bio::Graphics::Glyph::merge_parts
Bio::Graphics::Glyph::merged_alignment
Bio::Graphics::Glyph::minmax
Bio::Graphics::Glyph::oval
Bio::Graphics::Glyph::pentagram
Bio::Graphics::Glyph::pinsertion
Bio::Graphics::Glyph::primers
Bio::Graphics::Glyph::processed_transcript
Bio::Graphics::Glyph::protein
Bio::Graphics::Glyph::ragged_ends
Bio::Graphics::Glyph::redgreen_box
Bio::Graphics::Glyph::redgreen_segment
Bio::Graphics::Glyph::repeating_shape
Bio::Graphics::Glyph::rndrect
Bio::Graphics::Glyph::ruler_arrow
Bio::Graphics::Glyph::saw_teeth
Bio::Graphics::Glyph::segmented_keyglyph
Bio::Graphics::Glyph::segments
Bio::Graphics::Glyph::so_transcript
Bio::Graphics::Glyph::span
Bio::Graphics::Glyph::splice_site
Bio::Graphics::Glyph::stackedplot
Bio::Graphics::Glyph::ternary_plot
Bio::Graphics::Glyph::text_in_box
Bio::Graphics::Glyph::three_letters
Bio::Graphics::Glyph::tic_tac_toe
Bio::Graphics::Glyph::toomany
Bio::Graphics::Glyph::track
Bio::Graphics::Glyph::transcript
Bio::Graphics::Glyph::transcript2
Bio::Graphics::Glyph::translation
Bio::Graphics::Glyph::triangle
Bio::Graphics::Glyph::two_bolts
Bio::Graphics::Glyph::wave
Bio::Graphics::Glyph::weighted_arrow
Bio::Graphics::Glyph::whiskerplot
Bio::Graphics::Glyph::xyplot

like. SIXTY-SEVEN of them. it's giving glyph multiverse 🦋 every single one is its own little main character and i am obsessed. iykyk 💅

👑 AUTHOR 👑

Lincoln Stein — the literal icon, the blueprint, the moment 🎀

Lincoln Stein <lstein@cshl.org>

Copyright (c) 2001 Cold Spring Harbor Laboratory

and the legal bit, because we respect the paperwork bestie 📜✨:

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.

translation: free software, same terms as Perl itself, and if you wanna know about warranties, DISCLAIMER.txt is right there waiting for you 🫶

and that's the whole page, bestie!! 🌸 this was the User Contributed Perl Documentation version of Bio::G...:Glyph(3pm), running on perl v5.30.0 and dated 2019-11-25 — so if you're reading this from the future, hi, hope the syntax still hits 💀✨ go forth and subclass responsibly, mwah 💋

📦 where this page comes from

debian bookworm: libbio-graphics-perl 2.40-6 · Perl
debian trixie: libbio-graphics-perl 2.40-6 · Perl
ubuntu jammy: libbio-graphics-perl 2.40-6 · Perl
ubuntu noble: libbio-graphics-perl 2.40-6 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms