Provided by: libbio-graphics-perl_2.37-1_all bug

NAME

       Bio::Graphics::Glyph::trace - A glyph that visualizes a trace file

SYNOPSIS

        use Bio::Graphics;
        use Bio::Seq;
        use Bio::SeqFeature::Generic;

        my $bsg = 'Bio::SeqFeature::Generic';

        my $seq    = Bio::Seq->new(-length=>1000);

        my $whole  = $bsg->new(-display_name => 'Clone82',
                               -start        => 1,
                               -end          => $seq->length);

        my $trace1 = $bsg->new(-start        => 100,
                               -end          => 300,
                               -display_name => 'Excretory System',
                               -tag=>{
                                     trace=>"/path/to/trace/file.scf"
                                     }
                              );

        my $trace2 = $bsg->new(-start        => 500,
                               -end          => 800,
                               -display_name => 'Expression Pattern',
                               -tag=>{
                                     trace=>"http://localhost/traces/file2.scf"
                                     }
                              );

        my $panel = Bio::Graphics::Panel->new(-length    => $seq->length,
                                              -width     => 800,
                                              -truecolor => 1,
                                              -key_style => 'between',
                                              -pad_left  => 10,
                                              -pad_right => 10,
                                             );

        $panel->add_track($whole,
                          -glyph    => 'arrow',
                          -double   => 1,
                          -tick     => 2,
                          -label    => 1,
                          );

        $panel->add_track([$trace1,$trace2],
                          -glyph    => 'trace',
                          -label    => 1,
                          -key       => 'Example traces');

        binmode STDOUT;
        print $panel->png;

DESCRIPTION

       This glyph parses and displays trace information from a file.  A generic glyph is used to
       show where the trace is located and when the display is zoomed in enough to see the
       sequence, the trace will be drawn.

       The trace file can only be in SCF format.  The file can be located on the local filesystem
       or located at a remote URL (provided that you have the LWP module installed).

       Until an alignment feature is added to this glyph, the feature start and end must
       correspond exactly with the begining and end of the called sequence.  Meaning that even if
       the starting sequence is poor and doesn't match the sequence, it must still be included.

       The figure below illustrates this.  The trace and the reference sequence align from points
       "b" to "c".  The positions "A" and "D" need to be calculated and used in order for the
       trace to line up correctly.

                    A      b         c     D
         ref -------------------------------------------------
                           |||||||||||
         trace      ------------------------

       The glyph may be modified in the future to avoid this hassle (and it should still be
       compatible with the method described above).

   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

         -connector    Connector type                 0 (false)

         -connector_color
                       Connector color                black

         -label        Whether to draw a label        0 (false)

         -description  Whether to draw a description  0 (false)

         -hilite       Highlight color                undef (no color)

       The following additional options are available to the "image" glyph:

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

         -trace            Specify the trace path or URL     none
                           to use for this feature

         -trace_prefix     String to prepend to              none
                           each trace path. You may prepend
                           a directory or a partial URL.

         -trace_height     The height in pixels that the     90
                           trace will be drawn

         -vertical_spacing Vertical distance from the box    20
                           that shows the physical span of
                           the feature to the top of the
                           picture (in pixels)

         -glyph_delegate   Glyph to use when zoomed out too  'generic'
                           far for the trace to be drawn

         -a_color          Color of the line representing    'green'
                           Adenine on the trace

         -c_color          Color of the line representing    'blue'
                           Cytosine on the trace

         -g_color          Color of the line representing    'black'
                           Guanine on the trace

         -t_color          Color of the line representing    'red'
                           Thymine on the trace

         -show_border      Show the black border from        0
                           around the trace

         -abi_scale        The scale factor for abi          1
                           formatted files.  This is
                           multiplied against the max
                           trace value to determine the
                           hight of peaks.

   Specifying the Trace
       The path to the trace file can be specified in two ways. First, you can place it in the
       feature itself using a tag named "trace". Second, you can specify it as a track option
       using a callback:

         $panel->add_track(\@features,
                           -glyph=>'trace',
                           -trace => sub { my $feature = shift;
                                           my $trace_path = do_something();
                                           return $trace }
                           );

       You can of course give -trace a constant string, in which case each feature will show the
       same trace.

       The trace can be a file on the local operating system or a URL. However, URL fetching will
       only work if the LWP module is installed on your system.  Otherwise the glyph will fail
       with an error message.

       If the trace is a relative path (it does not begin with a slash or a URL protocol), then
       the contents of -trace_prefix will be prepended to it. This allows you to specify traces
       that are relative to a particular directory or a partial URL. Example:

         $panel->add_track(\@features,
                           -glyph => 'trace',
                           -trace_prefix => 'http://localhost/anatomy/trace-browser_files',
                          );

       This specifies that each feature's "trace" tag is to be appended to the partial localhost
       URL, thereby saving space.

   Glyph Delegation
       The trace glyph consists of two parts: an upper part that shows the extent of the feature
       in base pair coordinates, and a lower part that shows the trace.  The upper part will
       always be displayed.  The lower part will only display if zoomed close enough to see the
       sequence.

       By default the upper part uses the "generic" glyph, which is a simple rectangle filled
       with the bgcolor and outlined with the fgcolor. To use a different glyph in the upper
       part, specify the -glyph_delegate option, giving the name of the glyph you wish to use.
       For instance, to use the "span" glyph:

         $panel->add_track(\@features,
                           -glyph          => 'trace',
                           -glyph_delegate => 'span'
                          );

       This feature does not work with all glyphs, and in particular requires a recent CVS
       checkout of Bio::Perl to work properly with the "arrow", "span" and "primers" glyphs
       (support for the feature did not make it into version 1.5).

BUGS AND LIMITATIONS

       See the DESCRIPTION for an explaination of how to align the trace with the reference.

       The trace looks a little off when the feature is on the negative strand of the reference.
       This is because the letters are on the oppisite side of the position line.  This issue
       should be addressed.

       This glyph uses it's own version of the Bio::Graphics::Panel method, map_pt(), due to that
       method not behaving as needed.  The new copied method is called "trace_map_pt".

       If the trace file is gzipped, it will unzip it without destroying the gzipped file.
       However, it will also not remove the newly created file.  This will only be an issue when
       the files are stored locally, since web accessed trace files are stored as temp files
       anyway.

SEE ALSO

       Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::Graphics::Glyph::arrow,
       Bio::Graphics::Glyph::cds, Bio::Graphics::Glyph::crossbox, Bio::Graphics::Glyph::diamond,
       Bio::Graphics::Glyph::dna, Bio::Graphics::Glyph::dot, Bio::Graphics::Glyph::ellipse,
       Bio::Graphics::Glyph::extending_arrow, Bio::Graphics::Glyph::generic,
       Bio::Graphics::Glyph::graded_segments, Bio::Graphics::Glyph::heterogeneous_segments,
       Bio::Graphics::Glyph::image, Bio::Graphics::Glyph::line, Bio::Graphics::Glyph::pinsertion,
       Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::rndrect,
       Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::ruler_arrow,
       Bio::Graphics::Glyph::toomany, Bio::Graphics::Glyph::transcript,
       Bio::Graphics::Glyph::transcript2, Bio::Graphics::Glyph::translation,
       Bio::Graphics::Glyph::triangle, Bio::DB::GFF, Bio::SeqI, Bio::SeqFeatureI, Bio::Das, GD

AUTHOR

       Ben Faga <faga@cshl.edu>, Lincoln Stein <lstein@cshl.org>, Todd Harris <harris@cshl.org>

       Copyright (c) 2006 Cold Spring Harbor Laboratory

       This package and its accompanying libraries is free software; you can redistribute it
       and/or modify it under the terms of the GPL (either version 1, or at your option, any
       later version) or the Artistic License 2.0.  Refer to LICENSE for the full license text.
       In addition, please see DISCLAIMER.txt for disclaimers of warranty.