Bio::G...xyplot(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

✨ Bio::Graphics::Glyph::xyplot ✨

okay bestie, so this is the xyplot glyph from Bio::Graphics, and it's literally the one you want when your features aren't just sitting somewhere on the genome — they have vibes, aka numbers attached to them. 📈💖

It's a User Contributed Perl Documentation page, and honestly? She ate. Let's get into it.

🌸 NAME 🌸

Bio::Graphics::Glyph::xyplot — The xyplot glyph 👑

🦋 SYNOPSIS 🦋

  See L<Bio::Graphics::Panel> and L<Bio::Graphics::Glyph>.

that's it. that's the synopsis. she's low maintenance like that 💅

💜 DESCRIPTION 💜

So this glyph is for drawing features that have a position on the genome and a numeric value. We're talking gene prediction scores, motif-calling scores, percent similarity, microarray intensities — basically anything where you need a line plot and not just a cute little box. 🎀

The X axis = the position on the genome, same as every other glyph in the family. no cap.
The Y axis = the score. 📊

And the options let you control:

the height of the glyph
the maximum and minimum scores
the color of the line and the axis
the symbol you draw

The plot is designed to work on a single feature group that contains subfeatures. The subfeatures are the ones carrying the score info — they're the main characters here. 👑

The best way to arrange this is to create an aggregator for the feature. Let's take a histogram of repeat density as our example: intervals are spaced every megabase, and the score indicates the number of repeats in the interval. We'll assume the database has been loaded in such a way that:

each interval is a distinct feature
with the method name "density"
and the source name "repeat"

And also — all the repeat features are grouped together into a single group (the name of the group is irrelevant, don't stress about it bestie 🫶).

If you're using Bio::DB::GFF and Bio::Graphics directly, the sequence of events would look like this:

  my $agg = Bio::DB::GFF::Aggregator->new(-method    => 'repeat_density',
                                          -sub_parts => 'density:repeat');
  my $db  = Bio::DB::GFF->new(-dsn=>'my_database',
                              -aggregators => $agg);
  my $segment  = $db->segment('Chr1');
  my @features = $segment->features('repeat_density');

  my $panel = Bio::Graphics::Panel->new(-pad_left=>40,-pad_right=>40);
  $panel->add_track(\@features,
                    -glyph => 'xyplot',
                    -graph_type=>'points',
                    -point_symbol=>'disc',
                    -point_radius=>4,
                    -scale=>'both',
                    -height=>200,
  );

If you're using Generic Genome Browser instead, you'll add this to the configuration file:

  aggregators = repeat_density{density:repeat}
                clone alignment etc

⚠️ real talk: it is a good idea to add some padding to the left and right of the panel. Otherwise the scale will be partially cut off by the edge of the image. so sad. don't do that to yourself. 😭

The "boxes" variant lets you specify a pivot point so that scores above the pivot point get drawn in one color, and scores below get drawn in a different color. these "bicolor" plots are controlled by the options -bicolor_pivot, -pos_color and -neg_color, as described below. 🌈

🎀 OPTIONS 🎀

The following options are standard among all Glyphs. See Bio::Graphics::Glyph for a full explanation.

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

  -fgcolor      Foreground color               black

  -outlinecolor Synonym for -fgcolor

  -bgcolor      Background color               turquoise

  -fillcolor    Synonym for -bgcolor

  -linewidth    Line width                     1

  -height       Height of glyph                10

  -font         Glyph font                     gdSmallFont

  -label        Whether to draw a label        0 (false)

  -description  Whether to draw a description  0 (false)

  -hilite       Highlight color                undef (no color)

In addition, the xyplot glyph recognizes the following glyph-specific options:

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

  -max_score   Maximum value of the           Calculated
               feature's "score" attribute

  -min_score   Minimum value of the           Calculated
               feature's "score" attributes

  -graph_type  Type of graph to generate.     Histogram
               Options are: "histogram",
               "boxes", "line", "points",
               or "linepoints".

  -point_symbol Symbol to use. Options are    none
                "triangle", "square", "disc",
                "filled_triangle",
                "filled_square",
                "filled_disc","point",
                and "none".

  -point_radius Radius of the symbol, in      4
                pixels (does not apply
                to "point")

  -scale        Position where the Y axis     none
                scale is drawn if any.
                It should be one of
                "left", "right", "both" or "none"

  -graph_height Specify height of the graph   Same as the
                                              "height" option.

  -part_color  For boxes & points only,       none
               bgcolor of each part (should
               be a callback). Supersedes
               -neg_color.

  -scale_color Color of the scale             Same as fgcolor

  -clip        If min_score and/or max_score  false
               are manually specified, then
               setting this to true will
               cause values outside the
               range to be clipped.

  -bicolor_pivot                              0
               Where to pivot the two colors
               when drawing bicolor plots.
               Scores greater than this value will
               be drawn using -pos_color.
               Scores lower than this value will
               be drawn using -neg_color.

  -pos_color   When drawing bicolor plots,    same as bgcolor
               the fill color to use for
               values that are above
               the pivot point.

  -neg_color   When drawing bicolor plots,    same as bgcolor
               the fill color to use for values
               that are below the pivot point.

And here they are again as a bullet list, because we're extra like that 💖:

-max_score — Maximum value of the feature's "score" attribute. Default: Calculated.
-min_score — Minimum value of the feature's "score" attributes. Default: Calculated.
-graph_type — Type of graph to generate. Options are: "histogram", "boxes", "line", "points", or "linepoints". Default: Histogram.
-point_symbol — Symbol to use. Options are "triangle", "square", "disc", "filled_triangle", "filled_square", "filled_disc", "point", and "none". Default: none.
-point_radius — Radius of the symbol, in pixels (does not apply to "point"). Default: 4.
-scale — Position where the Y axis scale is drawn, if any. It should be one of "left", "right", "both" or "none". Default: none.
-graph_height — Specify height of the graph. Default: Same as the "height" option.
-part_color — For boxes & points only, bgcolor of each part (should be a callback). Supersedes -neg_color. Default: none.
-scale_color — Color of the scale. Default: Same as fgcolor.
-clip — If min_score and/or max_score are manually specified, then setting this to true will cause values outside the range to be clipped. Default: false.
-bicolor_pivot — Where to pivot the two colors when drawing bicolor plots. Scores greater than this value will be drawn using -pos_color. Scores lower than this value will be drawn using -neg_color. Default: 0.
-pos_color — When drawing bicolor plots, the fill color to use for values that are above the pivot point. Default: same as bgcolor.
-neg_color — When drawing bicolor plots, the fill color to use for values that are below the pivot point. Default: same as bgcolor.

💀 heads up: when you draw scales on the left or right, the scale is actually drawn a few pixels outside the boundaries of the glyph. So you may wish to add some padding to the image using -pad_left and -pad_right when you create the panel. iykyk.

The -part_color option can be used to color each part of the graph. Only the "boxes", "points" and "linepoints" styles are affected by this. Here's a simple example:

  $panel->add_track->(\@affymetrix_data,
                      -glyph      => 'xyplot',
                      -graph_type => 'boxes',
                      -part_color => sub {
                                   my $score = shift->score;
                                   return 'red' if $score < 0;
                                   return 'lightblue' if $score < 500;
                                   return 'blue'      if $score >= 500;
                                  }
                      );

🧚 METHODS 🧚

For those developers wishing to derive new modules based on this glyph, the main method to override is:

`'method_name' = $glyph->lookup_draw_method($type)`

This method accepts the name of a graph type (such as 'histogram') and returns the name of a method that will be called to draw the contents of the graph — for example, '_draw_histogram'. ✨

This method will be called with three arguments:

   $self->$draw_method($gd,$left,$top,$y_origin)

where:

$gd is the GD object
$left and $top are the left and right positions of the whole glyph (which includes the scale and label)
$y_origin is the position of the zero value on the y axis (in pixels)

By the time this method is called:

the y axis and labels will already have been drawn ✅
the scale of the drawing (in pixels per unit score) will have been calculated and stored in $self->{_scale} ✅
the y position (in pixels) of each point to graph will have been stored into the part, as $part->{_y_position} ✅

Hence you could draw a simple scatter plot with this code:

 sub lookup_draw_method {
    my $self = shift;
    my $type = shift;
    if ($type eq 'simple_scatterplot') {
      return 'draw_points';
    } else {
      return $self->SUPER::lookup_draw_method($type);
    }
 }

 sub draw_points {
  my $self = shift;
  my ($gd,$left,$top) = @_;
  my @parts   = $self->parts;
  my $bgcolor = $self->bgcolor;

  for my $part (@parts) {
    my ($x1,$y1,$x2,$y2) = $part->calculate_boundaries($left,$top);
    my $x = ($x1+$x2)/2;  # take center
    my $y = $part->{_y_position};
    $gd->setPixel($x,$y,$bgcolor);
 }

And one more thing bestie: lookup_draw_method() may return multiple method names if needed. Each will be called in turn. 🫶

`$y_position = $self->score2position($score)`

Translate a score into a y pixel position, obeying clipping rules and min and max values. simple as that. 🎯

🙈 BUGS 🙈

Please report them. (she's not gonna elaborate. iconic behavior honestly. 💅)

🌈 SEE ALSO 🌈

Bio::Graphics::Panel
Bio::Graphics::Track
Bio::Graphics::Glyph::transcript2
Bio::Graphics::Glyph::anchored_arrow
Bio::Graphics::Glyph::arrow
Bio::Graphics::Glyph::box
Bio::Graphics::Glyph::primers
Bio::Graphics::Glyph::segments
Bio::Graphics::Glyph::toomany
Bio::Graphics::Glyph::transcript

👑 AUTHOR 👑

Lincoln Stein <lstein@cshl.org>

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 💖 — shoutout to perl v5.30.0, dated 2019-11-25, for being the moment this masterpiece got snapped. slay, honestly. 🎀✨🦋

📦 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