Provided by: libbio-graphics-perl_2.40-2_all bug

NAME

       Bio::Graphics::Glyph::xyplot - The xyplot glyph

SYNOPSIS

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

DESCRIPTION

       This glyph is used for drawing features that have a position on the genome and a numeric
       value.  It can be used to represent gene prediction scores, motif-calling scores, percent
       similarity, microarray intensities, or other features that require a line plot.

       The X axis represents the position on the genome, as per all other glyphs.  The Y axis
       represents the score.  Options allow you to set the height of the glyph, the maximum and
       minimum scores, the color of the line and axis, and the symbol to draw.

       The plot is designed to work on a single feature group that contains subfeatures.  It is
       the subfeatures that carry the score information. The best way to arrange for this is to
       create an aggregator for the feature.  We'll take as an example a histogram of repeat
       density in which interval are spaced every megabase and the score indicates the number of
       repeats in the interval; we'll assume that the database has been loaded in in such a way
       that each interval is a distinct feature with the method name "density" and the source
       name "repeat".  Furthermore, all the repeat features are grouped together into a single
       group (the name of the group is irrelevant).  If you are 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 are using Generic Genome Browser, you will add this to the configuration file:

         aggregators = repeat_density{density:repeat}
                       clone alignment etc

       Note that 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.

       The "boxes" variant allows you to specify a pivot point such that scores above the pivot
       point are drawn in one color, and scores below are 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.

       Note that when drawing scales on the left or right that the scale is actually drawn a few
       pixels outside the boundaries of the glyph.  You may wish to add some padding to the image
       using -pad_left and -pad_right when you create the panel.

       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), and $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, and 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);
            }

           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.

BUGS

       Please report them.

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>

       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.