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

Bio::G...::trace 💖 NAME 🌈

okay bestie so this is a glyph — like a little drawing unit — that visualizes a trace file ✨ it's part of the Bio::Graphics fam, it's a 3pm Perl module page, and yes we are gonna go through the WHOLE thing together, no skimming 💅

---

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready, not a single character changed, i promise 🫶

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;

like. she's gorgeous. look at her go 🎀

---

🦋 DESCRIPTION 🦋

So this glyph parses and displays trace information from a file. A generic glyph gets used to show where the trace is located, and then — the moment you zoom in enough to actually see the sequence — the trace gets drawn. main character entrance, honestly 👑

⚠️ the trace file can only be in SCF format. that's the rule. no other formats. don't try it.

The file can live on your local filesystem or at a remote URL — but only if you have the LWP module installed. no LWP, no remote traces, simple as 💀

Okay so this next bit is important and lowkey annoying: until an alignment feature gets added to this glyph, the feature start and end must correspond exactly with the beginning and end of the called sequence. Meaning — and i need you to hear me — even if the starting sequence is poor and doesn't match the sequence, it must still be included. yes. even then. 🙈

The figure below shows the whole situation. 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 might get modified in the future to avoid this hassle — and it should still be compatible with the method described above, so don't panic ✨

---

✨ OPTIONS ✨

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

• -fgcolor — Foreground color. Default: black
• -outlinecolor — Synonym for -fgcolor
• -bgcolor — Background color. Default: turquoise
• -fillcolor — Synonym for -bgcolor
• -linewidth — Line width. Default: 1
• -height — Height of glyph. Default: 10
• -font — Glyph font. Default: gdSmallFont
• -connector — Connector type. Default: 0 (false)
• -connector_color — Connector color. Default: black
• -label — Whether to draw a label. Default: 0 (false)
• -description — Whether to draw a description. Default: 0 (false)
• -hilite — Highlight color. Default: undef (no color)

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

• -trace — Specify the trace path or URL to use for this feature. Default: none
• -trace_prefix — String to prepend to each trace path. You may prepend a directory or a partial URL. Default: none
• -trace_height — The height in pixels that the trace will be drawn. Default: 90
• -vertical_spacing — Vertical distance from the box that shows the physical span of the feature to the top of the picture (in pixels). Default: 20
• -glyph_delegate — Glyph to use when zoomed out too far for the trace to be drawn. Default: 'generic'
• -a_color — Color of the line representing Adenine on the trace. Default: 'green'
• -c_color — Color of the line representing Cytosine on the trace. Default: 'blue'
• -g_color — Color of the line representing Guanine on the trace. Default: 'black'
• -t_color — Color of the line representing Thymine on the trace. Default: 'red'
• -show_border — Show the black border from around the trace. Default: 0
• -abi_scale — The scale factor for abi formatted files. This is multiplied against the max trace value to determine the hight of peaks. Default: 1

---

🧚 Specifying the Trace 🧚

There are two ways to tell her where the trace file lives, bestie:

1. put it in the feature itself using a tag named "trace"
2. specify it as a track option using a callback, like so:

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

And yes, you can totally give -trace a constant string — in which case every single feature shows the same trace. icon of consistency tbh 🫶

The trace can be a file on the local operating system or a URL. However — URL fetching only works if the LWP module is installed on your system. Otherwise the glyph will fail with an error message. no cap, she will simply not do it 😭

If the trace is a relative path — meaning it doesn't begin with a slash or a URL protocol — then the contents of -trace_prefix get prepended to it. This lets you 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',
                 );

So each feature's "trace" tag gets appended to that partial localhost URL, thereby saving space. efficient queen 🌈

---

👑 Glyph Delegation 👑

The trace glyph is literally two parts, okay:

• an upper part that shows the extent of the feature in base pair coordinates
• 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. Wanna swap it? Specify the -glyph_delegate option and give the name of the glyph you want instead. Like, for instance, to use the "span" glyph:

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

⚠️ heads up: this feature does not work with all glyphs. And in particular it requires a recent CVS checkout of Bio::Perl to work properly with the "arrow", "span" and "primers" glyphs — because support for the feature did not make it into version 1.5. i know. i know. 💀

---

💀 BUGS AND LIMITATIONS 💀

okay so the messy bits, we're listing them all, no hiding 🙈

• See the DESCRIPTION for an explanation 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. (yes that's how it's spelled in the source, i'm not touching it, it's canon now 💅)
• 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". her little clone. iconic behavior fr fr.
• 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 is only an issue when the files are stored locally, since web accessed trace files are stored as temp files anyway.

---

🔥 SEE ALSO 🔥

the whole extended family, all of them, every last one 🫶

• 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 💖

the legends themselves:

• 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.

---

okay that's the whole page bestie, you ate it, every flag, every default, every bug, every author, all of it 💅✨ this was perl v5.30.0, dated 2019-11-25, and it's the Bio::G...::trace(3pm) page from the User Contributed Perl Documentation — mwah, go build something cute 🦋🎀