.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Bio::Graphics::Panel 3pm" .TH Bio::Graphics::Panel 3pm "2019-11-25" "perl v5.30.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::Graphics::Panel \- Generate GD images of Bio::Seq objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # This script parses a GenBank or EMBL file named on the command \& # line and produces a PNG rendering of it. Call it like this: \& # render.pl my_file.embl | display \- \& \& use strict; \& use Bio::Graphics; \& use Bio::SeqIO; \& \& my $file = shift or die "provide a sequence file as the argument"; \& my $io = Bio::SeqIO\->new(\-file=>$file) or die "could not create Bio::SeqIO"; \& my $seq = $io\->next_seq or die "could not find a sequence in the file"; \& \& my @features = $seq\->all_SeqFeatures; \& \& # sort features by their primary tags \& my %sorted_features; \& for my $f (@features) { \& my $tag = $f\->primary_tag; \& push @{$sorted_features{$tag}},$f; \& } \& \& my $panel = Bio::Graphics::Panel\->new( \& \-length => $seq\->length, \& \-key_style => \*(Aqbetween\*(Aq, \& \-width => 800, \& \-pad_left => 10, \& \-pad_right => 10, \& ); \& $panel\->add_track( arrow => Bio::SeqFeature::Generic\->new(\-start=>1, \& \-end=>$seq\->length), \& \-bump => 0, \& \-double=>1, \& \-tick => 2); \& $panel\->add_track(generic => Bio::SeqFeature::Generic\->new(\-start=>1, \& \-end=>$seq\->length), \& \-glyph => \*(Aqgeneric\*(Aq, \& \-bgcolor => \*(Aqblue\*(Aq, \& \-label => 1, \& ); \& \& # general case \& my @colors = qw(cyan orange blue purple green chartreuse magenta yellow aqua); \& my $idx = 0; \& for my $tag (sort keys %sorted_features) { \& my $features = $sorted_features{$tag}; \& $panel\->add_track($features, \& \-glyph => \*(Aqgeneric\*(Aq, \& \-bgcolor => $colors[$idx++ % @colors], \& \-fgcolor => \*(Aqblack\*(Aq, \& \-font2color => \*(Aqred\*(Aq, \& \-key => "${tag}s", \& \-bump => +1, \& \-height => 8, \& \-label => 1, \& \-description => 1, \& ); \& } \& \& print $panel\->png; \& $panel\->finished; \& \& exit 0; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Bio::Graphics::Panel class provides drawing and formatting services for any object that implements the Bio::SeqFeatureI interface, including Ace::Sequence::Feature and Das::Segment::Feature objects. It can be used to draw sequence annotations, physical (contig) maps, or any other type of map in which a set of discrete ranges need to be laid out on the number line. .PP The module supports a drawing style in which each type of feature occupies a discrete \*(L"track\*(R" that spans the width of the display. Each track will have its own distinctive \*(L"glyph\*(R", a configurable graphical representation of the feature. .PP The module also supports a more flexible style in which several different feature types and their associated glyphs can occupy the same track. The choice of glyph is under run-time control. .PP Semantic zooming (for instance, changing the type of glyph depending on the density of features) is supported by a callback system for configuration variables. The module has built-in support for Bio::Das stylesheets, and stylesheet-driven configuration can be intermixed with semantic zooming, if desired. .PP You can add a key to the generated image using either of two key styles. One style places the key captions at the top of each track. The other style generates a graphical key at the bottom of the image. .PP Note that this module depends on \s-1GD.\s0 The optional \s-1SVG\s0 output depends on \s-1GD::SVG\s0 and \s-1SVG.\s0 .PP The installed script glyph_help.pl provides quick help on glyphs and their options. .SH "METHODS" .IX Header "METHODS" This section describes the class and object methods for Bio::Graphics::Panel. .PP Typically you will begin by creating a new Bio::Graphics::Panel object, passing it the desired width of the image to generate and an origin and length describing the coordinate range to display. The Bio::Graphics::Panel\->\fBnew()\fR method has many configuration variables that allow you to control the appearance of the image. .PP You will then call \fBadd_track()\fR one or more times to add sets of related features to the picture. \fBadd_track()\fR places a new horizontal track on the image, and is likewise highly configurable. When you have added all the features you desire, you may call \fBpng()\fR to convert the image into a PNG-format image, or \fBboxes()\fR to return coordinate information that can be used to create an imagemap. .SS "\s-1CONSTRUCTORS\s0" .IX Subsection "CONSTRUCTORS" \&\fBnew()\fR is the constructor for Bio::Graphics::Panel: .ie n .IP "$panel = Bio::Graphics::Panel\->new(@options)" 4 .el .IP "\f(CW$panel\fR = Bio::Graphics::Panel\->new(@options)" 4 .IX Item "$panel = Bio::Graphics::Panel->new(@options)" The \fBnew()\fR method creates a new panel object. The options are a set of tag/value pairs as follows: .Sp .Vb 2 \& Option Value Default \& \-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\- \& \& \-offset Base pair to place at extreme left none \& of image, in zero\-based coordinates \& \& \-length Length of sequence segment, in bp none \& \& \-start Start of range, in 1\-based none \& coordinates. \& \& \-stop Stop of range, in 1\-based none \& coordinates. \& \& \-end Same as \-stop. \& \& \-segment A Bio::SeqI or Das::Segment none \& object, used to derive sequence \& range if not otherwise specified. \& \& \-width Desired width of image, in pixels 600 \& \& \-spacing Spacing between tracks, in pixels 5 \& \& \-pad_top Additional whitespace between top 0 \& of image and contents, in pixels \& \& \-pad_bottom Additional whitespace between top 0 \& of image and bottom, in pixels \& \& \-pad_left Additional whitespace between left 0 \& of image and contents, in pixels \& \& \-pad_right Additional whitespace between right 0 \& of image and bottom, in pixels \& \& \-bgcolor Background color for the panel as a white \& whole \& \& \-key_color Background color for the key printed wheat \& at bottom of panel (if any) \& \& \-key_spacing Spacing between key glyphs in the 10 \& key printed at bottom of panel \& (if any) \& \& \-key_font Font to use in printed key gdMediumBoldFont \& captions. \& \& \-key_style Whether to print key at bottom of none \& panel ("bottom"), between each \& track ("between"), to the left of \& each track ("left"), to the right \& of each track ("right") or \& not at all ("none"). \& \& \-add_category_labels false \& Whether to add the "category" to \& the track key. The category is \& an optional argument that can \& be attached to each track. If \& a category is present, and this \& option is true, then the category \& will be added to the track label \& in parentheses. For example, if \& \-key is "Protein matches" and \& \-category is "vertebrate", then \& the track will be labeled \& "Protein matches (vertebrate)". \& \& \-auto_pad If "left" or "right" keys are in use true \& then setting auto_pad to a true value \& will allow the panel to adjust its \& width in order to accommodate the \& length of the longest key. \& \& \-empty_tracks What to do when a track is empty. suppress \& Options are to suppress the track \& completely ("suppress"), to show just \& the key in "between" mode ("key"), \& to draw a thin grey line ("line"), \& or to draw a dashed line ("dashed"). \& \& \-flip flip the drawing coordinates left false \& to right, so that lower coordinates \& are to the right. This can be \& useful for drawing (\-) strand \& features. \& \& \-all_callbacks Whether to invoke callbacks on false \& the automatic "track" and "group" \& glyphs. \& \& \-grid Whether to draw a vertical grid in false \& the background. Pass a scalar true \& value to have a grid drawn at \& regular intervals (corresponding \& to the minor ticks of the arrow \& glyph). Pass an array reference \& to draw the grid at the specified \& positions. \& \& \-gridcolor Color of the grid lightcyan \& \& \-gridmajorcolor Color of grid major intervals cyan \& \& \-extend_grid If true, extend the grid into the pad false \& top and pad_bottom regions \& \& \-background An image or callback to use for the none \& background of the image. Will be \& invoked I drawing the grid. \& \& \-postgrid An image or callback to use for the none \& background of the image. Will be \& invoked I drawing the grid. \& \& \-truecolor Create a truecolor (24\-bit) image. false \& Useful when working with the \& "image" glyph. \& \& \-truetype Render text using scalable vector false \& fonts rather than bitmap fonts. \& \& \-image_class To create output in scalable vector \& graphics (SVG), optionally pass the image \& class parameter \*(AqGD::SVG\*(Aq. Defaults to \& using vanilla GD. See the corresponding \& image_class() method below for details. \& \& \-link, \-title, \-target \& These options are used when creating imagemaps \& for display on the web. See L. .Ve .Sp Typically you will pass \fBnew()\fR an object that implements the Bio::RangeI interface, providing a \fBlength()\fR method, from which the panel will derive its scale. .Sp .Vb 2 \& $panel = Bio::Graphics::Panel\->new(\-segment => $sequence, \& \-width => 800); .Ve .Sp \&\fBnew()\fR will return undef in case of an error. .Sp Note that if you use the \*(L"left\*(R" or \*(L"right\*(R" key styles, you are responsible for allocating sufficient \-pad_left or \-pad_right room for the labels to appear. The necessary width is the number of characters in the longest key times the font width (gdMediumBoldFont by default) plus 3 pixels of internal padding. The simplest way to calculate this is to iterate over the possible track labels, find the largest one, and then to compute its width using the formula: .Sp .Vb 1 \& $width = gdMediumBoldFont\->width * length($longest_key) +3; .Ve .Sp In order to obtain scalable vector graphics (\s-1SVG\s0) output, you should pass \fBnew()\fR the \-image_class=>'\s-1GD::SVG\s0' parameter. This will cause Bio::Graphics::Panel to load the optional \s-1GD::SVG\s0 module. See the \fBgd()\fR and \fBsvg()\fR methods below for additional information. .Sp You can tile an image onto the panel either before or after it draws the grid. Simply provide the filename of the image in the \-background or \-postgrid options. The image file must be of type \s-1PNG, JPEG, XBM\s0 or \&\s-1GIF\s0 and have a filename ending in .png, .jpg, .jpeg, .xbm or .gif. .Sp You can also pass a code ref for the \-background or \-postgrid option, in which case the subroutine will be invoked at the appropriate time with the GD::Image object and the Panel object as its two arguments. You can then use the panel methods to map base pair coordinates into pixel coordinates and do some custom drawing. For example, this code fragment will draw a gray rectangle between bases 500 and 600 to indicate a \*(L"gap\*(R" in the sequence: .Sp .Vb 10 \& my $panel = Bio::Graphics::Panel\->new(\-segment=>$segment, \& \-grid=>1, \& \-width=>600, \& \-postgrid=> \e&draw_gap); \& sub gap_it { \& my $gd = shift; \& my $panel = shift; \& my ($gap_start,$gap_end) = $panel\->location2pixel(500,600); \& my $top = $panel\->top; \& my $bottom = $panel\->bottom; \& my $gray = $panel\->translate_color(\*(Aqgray\*(Aq); \& $gd\->filledRectangle($gap_start,$top,$gap_end,$bottom,$gray); \&} .Ve .Sp The \fB\-truetype\fR argument will activate rendering of labels using antialiased vector fonts. If it is a value of \*(L"1\*(R", then labels will be rendered using the default font (Verdana). Pass a font name to use this font as the default: .Sp .Vb 1 \& \-truetype => \*(AqTimes New Roman\*(Aq, .Ve .Sp Note that you can change the font on a track-by-track basis simply by using a truetype font name as \fBadd_track()\fR's \-font argument. .SS "\s-1OBJECT METHODS\s0" .IX Subsection "OBJECT METHODS" .ie n .IP "$track = $panel\->add_track($glyph,$features,@options)" 4 .el .IP "\f(CW$track\fR = \f(CW$panel\fR\->add_track($glyph,$features,@options)" 4 .IX Item "$track = $panel->add_track($glyph,$features,@options)" The \fBadd_track()\fR method adds a new track to the image. .Sp Tracks are horizontal bands which span the entire width of the panel. Each track contains a number of graphical elements called \*(L"glyphs\*(R", corresponding to a sequence feature. .Sp There are a large number of glyph types. By default, each track will be homogeneous on a single glyph type, but you can mix several glyph types on the same track by providing a code reference to the \-glyph argument. Other options passed to \fBadd_track()\fR control the color and size of the glyphs, whether they are allowed to overlap, and other formatting attributes. The height of a track is determined from its contents and cannot be directly influenced. .Sp The first two arguments are the glyph name and an array reference containing the list of features to display. The order of the arguments is irrelevant, allowing either of these idioms: .Sp .Vb 2 \& $panel\->add_track(arrow => \e@features); \& $panel\->add_track(\e@features => \*(Aqarrow\*(Aq); .Ve .Sp The glyph name indicates how each feature is to be rendered. A variety of glyphs are available, and the number is growing. You may omit the glyph name entirely by providing a \fB\-glyph\fR argument among \&\f(CW@options\fR, as described below. .Sp Currently, the following glyphs are available: .Sp .Vb 2 \& Name Description \& \-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& anchored_arrow \& a span with vertical bases |\-\-\-\-\-\-\-\-\-|. If one or \& the other end of the feature is off\-screen, the base \& will be replaced by an arrow. \& \& arrow An arrow; can be unidirectional or bidirectional. \& It is also capable of displaying a scale with \& major and minor tickmarks, and can be oriented \& horizontally or vertically. \& \& box A filled rectangle, nondirectional. Subfeatures are ignored. \& \& cds Draws CDS features, using the phase information to \& show the reading frame usage. At high magnifications \& draws the protein translation. \& \& crossbox A box with a big "X" inside it. \& \& diamond A diamond, useful for point features like SNPs. \& \& dna At high magnification draws the DNA sequence. At \& low magnifications draws the GC content. \& \& dot A circle, useful for point features like SNPs, stop \& codons, or promoter elements. \& \& ellipse An oval. \& \& extending_arrow \& Similar to arrow, but a dotted line indicates when the \& feature extends beyond the end of the canvas. \& \& generic A filled rectangle, nondirectional. Subfeatures are shown \& as rectangles that are not connected together. \& \& graded_segments \& Similar to segments, but the intensity of the color \& is proportional to the score of the feature. This \& is used for showing the intensity of blast hits or \& other alignment features. \& \& group A group of related features connected by a dashed line. \& This is used internally by Panel. \& \& image A pixmap image that will be layered on top of the graphic. \& \& heterogeneous_segments \& Like segments, but you can use the source field of the feature \& to change the color of each segment. \& \& line A simple line. \& \& pinsertion A triangle designed to look like an insertion location \& (e.g. a transposon insertion). \& \& processed_transcript multi\-purpose representation of a spliced mRNA, including \& positions of UTRs \& \& primers Two inward pointing arrows connected by a line. \& Used for STSs. \& \& redgreen_box A box that changes from green\->yellow\->red as the score \& of the feature increases from 0.0 to 1.0. Useful for \& representing microarray results. \& \& rndrect A round\-cornered rectangle. \& \& segments A set of filled rectangles connected by solid lines. \& Used for interrupted features, such as gapped \& alignments. \& \& ruler_arrow An arrow with major and minor tick marks and interval \& labels. \& \& toomany Tries to show many features as a cloud. Not very successful. \& \& track A group of related features not connected by a line. \& This is used internally by Panel. \& \& transcript Similar to segments, but the connecting line is \& a "hat" shape, and the direction of transcription \& is indicated by a small arrow. \& \& transcript2 Similar to transcript, but the direction of \& transcription is indicated by a terminal exon \& in the shape of an arrow. \& \& translation 1, 2 and 3\-frame translations. At low magnifications, \& can be configured to show start and stop codon locations. \& At high magnifications, shows the multi\-frame protein \& translation. \& \& triangle A triangle whose width and orientation can be altered. \& \& xyplot Histograms and other graphs plotted against the genome. \& \& stackedplot A column plot showing multiple data series across multiple categories. \& \& ternary_plot Ternary (triangle) plots. \& \& whiskerplot Box and whisker plot for statistical data .Ve .Sp If the glyph name is omitted from \fBadd_track()\fR, the \*(L"generic\*(R" glyph will be used by default. To get more information about a glyph, run perldoc on \*(L"Bio::Graphics::Glyph::glyphname\*(R", replacing \*(L"glyphname\*(R" with the name of the glyph you are interested in. .Sp The \*(L"box\*(R" glyph is optimized for single features with no subfeatures. If you are drawing such a feature, using \*(L"box\*(R" will be noticeably faster than \*(L"generic.\*(R" .Sp The \f(CW@options\fR array is a list of name/value pairs that control the attributes of the track. Some options are interpretered directly by the track. Others are passed down to the individual glyphs (see \&\*(L"\s-1GLYPH OPTIONS\*(R"\s0). The following options are track-specific: .Sp .Vb 2 \& Option Description Default \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \& \& \-tkcolor Track color white \& \& \-glyph Glyph class to use. "generic" \& \& \-color_series Dynamically choose false \& bgcolor. \& \& \-stylesheet Bio::Das::Stylesheet to none \& use to generate glyph \& classes and options. .Ve .Sp \&\fB\-tkcolor\fR controls the background color of the track as a whole. .Sp \&\fB\-glyph\fR controls the glyph type. If present, it supersedes the glyph name given in the first or second argument to \fBadd_track()\fR. The value of \fB\-glyph\fR may be a constant string, a hash reference, or a code reference. In the case of a constant string, that string will be used as the class name for all generated glyphs. If a hash reference is passed, then the feature's \fBprimary_tag()\fR will be used as the key to the hash, and the value, if any, used to generate the glyph type. If a code reference is passed, then this callback will be passed arguments consisting of the feature and the panel object. The callback is expected to examine the feature and return a glyph name as its single result. .Sp Example: .Sp .Vb 5 \& $panel\->add_track(\e@exons, \& \-glyph => sub { my ($feature,$panel) = @_; \& $feature\->source_tag eq \*(Aqcurated\*(Aq \& ? \*(Aqellipse\*(Aq : \*(Aqbox\*(Aq; } \& ); .Ve .Sp The \fB\-stylesheet\fR argument is used to pass a Bio::Das stylesheet object to the panel. This stylesheet will be called to determine both the glyph and the glyph options. If both a stylesheet and direct options are provided, the latter take precedence. .Sp The \fB\-color_series\fR argument causes the track to ignore the \-bgcolor setting and instead to assign glyphs a series of contrasting colors. This is usually used in combination with \-bump=>'overlap' in order to create overlapping features. A true value activates the color series. You may adjust the default color series using the \&\fB\-color_cycle\fR option, which is either a reference to an array of Bio::Graphics color values, or a space-delimited string of color names/value. .Sp If successful, \fBadd_track()\fR returns an Bio::Graphics::Glyph object. You can use this object to add additional features or to control the appearance of the track with greater detail, or just ignore it. Tracks are added in order from the top of the image to the bottom. To add tracks to the top of the image, use \fBunshift_track()\fR. .Sp \&\fBAdding groups of features:\fR It is not uncommon to add a group of features which are logically connected, such as the 5' and 3' ends of \&\s-1EST\s0 reads. To group features into sets that remain on the same horizontal position and bump together, pass the sets as an anonymous array. For example: .Sp .Vb 4 \& $panel\->add_track(segments => [[$abc_5,$abc_3], \& [$xxx_5,$xxx_3], \& [$yyy_5,$yyy_3]] \& ); .Ve .Sp Typical usage is: .Sp .Vb 6 \& $panel\->add_track( transcript => \e@genes, \& \-fillcolor => \*(Aqgreen\*(Aq, \& \-fgcolor => \*(Aqblack\*(Aq, \& \-bump => +1, \& \-height => 10, \& \-label => 1); .Ve .Sp The track object is simply a specialized type of glyph. See Bio::Graphics::Glyph for a description of the methods that it supports. .ie n .IP "$track = unshift_track($glyph,$features,@options)" 4 .el .IP "\f(CW$track\fR = unshift_track($glyph,$features,@options)" 4 .IX Item "$track = unshift_track($glyph,$features,@options)" \&\fBunshift_track()\fR works like \fBadd_track()\fR, except that the new track is added to the top of the image rather than the bottom. .ie n .IP "$track = $panel\->insert_track($position,$glyph,$features,@options)" 4 .el .IP "\f(CW$track\fR = \f(CW$panel\fR\->insert_track($position,$glyph,$features,@options)" 4 .IX Item "$track = $panel->insert_track($position,$glyph,$features,@options)" This works like \fBadd_track()\fR, but the track is inserted into the indicated position. The track will be inserted \fBbefore\fR the indicated position; thus specify a track of 0 to insert the new track at the beginning. .ie n .IP "$gd = $panel\->gd([$gd])" 4 .el .IP "\f(CW$gd\fR = \f(CW$panel\fR\->gd([$gd])" 4 .IX Item "$gd = $panel->gd([$gd])" The \fBgd()\fR method lays out the image and returns a GD::Image object containing it. You may then call the GD::Image object's \fBpng()\fR or \&\fBjpeg()\fR methods to get the image data. .Sp Optionally, you may pass \fBgd()\fR a preexisting GD::Image object that you wish to draw on top of. If you do so, you should call the \fBwidth()\fR and \&\fBheight()\fR methods first to ensure that the image has sufficient dimensions. .Sp If you passed \fBnew()\fR the \-image_class=>'\s-1GD::SVG\s0' parameter, the \fBgd()\fR method returns a GD::SVG::Image object. This object overrides GD::Image methods in order to generate \s-1SVG\s0 output. It behaves exactly as described for GD::Image objects with one exception: it implements and \&\fBsvg()\fR method instead of the \fBpng()\fR or \fBjpeg()\fR methods. Currently there is no direct access to underlying \s-1SVG\s0 calls but this is subject to change in the future. .ie n .IP "$png = $panel\->png" 4 .el .IP "\f(CW$png\fR = \f(CW$panel\fR\->png" 4 .IX Item "$png = $panel->png" The \fBpng()\fR method returns the image as a PNG-format drawing, without the intermediate step of returning a GD::Image object. .ie n .IP "$svg = $panel\->svg" 4 .el .IP "\f(CW$svg\fR = \f(CW$panel\fR\->svg" 4 .IX Item "$svg = $panel->svg" The \fBsvg()\fR method returns the image in an XML-ified \s-1SVG\s0 format. .ie n .IP "$panel\->finished" 4 .el .IP "\f(CW$panel\fR\->finished" 4 .IX Item "$panel->finished" Bio::Graphics creates memory cycles. When you are finished with the panel, you should call its \fBfinished()\fR method. Otherwise you will have memory leaks. This is only an issue if you're going to create several panels in a single program. .ie n .IP "$image_class = $panel\->image_class" 4 .el .IP "\f(CW$image_class\fR = \f(CW$panel\fR\->image_class" 4 .IX Item "$image_class = $panel->image_class" The \fBimage_class()\fR method returns the current drawing package being used, currently one of \s-1GD\s0 or \s-1GD::SVG.\s0 This is primarily used internally to ensure that calls to \s-1GD\s0's exported methods are called in an object-oriented manner to avoid compile time undefined string errors. This is usually not needed for external use. .ie n .IP "$image_package = $panel\->image_package" 4 .el .IP "\f(CW$image_package\fR = \f(CW$panel\fR\->image_package" 4 .IX Item "$image_package = $panel->image_package" This accessor method, like \fBimage_class()\fR above is provided as a convenience. It returns the current image package in use, currently one of GD::Image or GD::SVG::Image. This is not normally used externally. .ie n .IP "$polygon_package = $panel\->polygon_package" 4 .el .IP "\f(CW$polygon_package\fR = \f(CW$panel\fR\->polygon_package" 4 .IX Item "$polygon_package = $panel->polygon_package" This accessor method, like \fBimage_package()\fR above is provided as a convenience. It returns the current polygon package in use, currently one of GD::Polygon or GD::SVG::Polygon. This is not normally used externally except in the design of glyphs. .ie n .IP "$boxes = $panel\->boxes" 4 .el .IP "\f(CW$boxes\fR = \f(CW$panel\fR\->boxes" 4 .IX Item "$boxes = $panel->boxes" .PD 0 .ie n .IP "@boxes = $panel\->boxes" 4 .el .IP "\f(CW@boxes\fR = \f(CW$panel\fR\->boxes" 4 .IX Item "@boxes = $panel->boxes" .PD The \fBboxes()\fR method returns a list of arrayrefs containing the coordinates of each glyph. The method is useful for constructing an image map. In a scalar context, \fBboxes()\fR returns an arrayref. In an list context, the method returns the list directly. .Sp Each member of the list is an arrayref of the following format: .Sp .Vb 1 \& [ $feature, $x1, $y1, $x2, $y2, $track ] .Ve .Sp The first element is the feature object; either an Ace::Sequence::Feature, a Das::Segment::Feature, or another Bioperl Bio::SeqFeatureI object. The coordinates are the topleft and bottomright corners of the glyph, including any space allocated for labels. The track is the Bio::Graphics::Glyph object corresponding to the track that the feature is rendered inside. .ie n .IP "$boxes = $panel\->key_boxes" 4 .el .IP "\f(CW$boxes\fR = \f(CW$panel\fR\->key_boxes" 4 .IX Item "$boxes = $panel->key_boxes" .PD 0 .ie n .IP "@boxes = $panel\->key_boxes" 4 .el .IP "\f(CW@boxes\fR = \f(CW$panel\fR\->key_boxes" 4 .IX Item "@boxes = $panel->key_boxes" .PD Returns the positions of the track keys as an arrayref or a list, depending on context. Each value in the list is an arrayref of format: .Sp .Vb 1 \& [ $key_text, $x1, $y1, $x2, $y2, $track ] .Ve .ie n .IP "$position = $panel\->track_position($track)" 4 .el .IP "\f(CW$position\fR = \f(CW$panel\fR\->track_position($track)" 4 .IX Item "$position = $panel->track_position($track)" After calling \fBgd()\fR or \fBboxes()\fR, you can learn the resulting Y coordinate of a track by calling \fBtrack_position()\fR with the value returned by \fBadd_track()\fR or \fBunshift_track()\fR. This will return undef if called before \fBgd()\fR or \fBboxes()\fR or with an invalid track. .ie n .IP "$rotate = $panel\->rotate([$new_value])" 4 .el .IP "\f(CW$rotate\fR = \f(CW$panel\fR\->rotate([$new_value])" 4 .IX Item "$rotate = $panel->rotate([$new_value])" Gets or sets the \*(L"rotate\*(R" flag. If rotate is set to true (default false), then calls to \fBgd()\fR, \fBpng()\fR, \fBgif()\fR, \fBboxes()\fR, and \fBimage_and_map()\fR will all return an image and/or imagemap that has been rotated to the right by 90 degrees. This is mostly useful for drawing karyotypes with the ideogram glyph, in order to rotate the chromosomes into the usual vertical position. .ie n .IP "@pixel_coords = $panel\->location2pixel(@feature_coords)" 4 .el .IP "\f(CW@pixel_coords\fR = \f(CW$panel\fR\->location2pixel(@feature_coords)" 4 .IX Item "@pixel_coords = $panel->location2pixel(@feature_coords)" Public routine to map feature coordinates (in base pairs) into pixel coordinates relative to the left-hand edge of the picture. If you define a \-background callback, the callback may wish to invoke this routine in order to translate base coordinates into pixel coordinates. .ie n .IP "$left = $panel\->left" 4 .el .IP "\f(CW$left\fR = \f(CW$panel\fR\->left" 4 .IX Item "$left = $panel->left" .PD 0 .ie n .IP "$right = $panel\->right" 4 .el .IP "\f(CW$right\fR = \f(CW$panel\fR\->right" 4 .IX Item "$right = $panel->right" .ie n .IP "$top = $panel\->top" 4 .el .IP "\f(CW$top\fR = \f(CW$panel\fR\->top" 4 .IX Item "$top = $panel->top" .ie n .IP "$bottom = $panel\->bottom" 4 .el .IP "\f(CW$bottom\fR = \f(CW$panel\fR\->bottom" 4 .IX Item "$bottom = $panel->bottom" .PD Return the pixel coordinates of the \fIdrawing area\fR of the panel, that is, exclusive of the padding. .SH "GLYPH OPTIONS" .IX Header "GLYPH OPTIONS" Each glyph has its own specialized subset of options, but some are shared by all glyphs: .PP .Vb 2 \& Option Description Default \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \& \& \-key Description of track for undef \& display in the track label. \& \& \-category The category of the track undef \& for display in the \& track label. \& \& \-fgcolor Foreground color black \& \& \-bgcolor Background color turquoise \& \& \-linewidth Width of lines drawn by 1 \& glyph \& \& \-height Height of glyph 10 \& \& \-font Glyph font gdSmallFont \& \& \-fontcolor Primary font color black \& \& \-font2color Secondary font color turquoise \& \& \-opacity Value from 0.0 (invisible) 1.0 \& to 1.0 (opaque) which \& controls the translucency \& of overlapping features. \& \& \-label Whether to draw a label false \& \& \-description Whether to draw a false \& description \& \& \-bump Bump direction 0 \& \& \-sort_order Specify layout sort order "default" \& \& \-feature_limit \& Maximum number of features undef (unlimited) \& to display \& \& \-bump_limit Maximum number of levels undef (unlimited) \& to bump \& \& \-hbumppad Additional horizontal 0 \& padding between bumped \& features \& \& \-strand_arrow Whether to indicate undef (false) \& strandedness \& \& \-stranded Synonym for \-strand_arrow undef (false) \& \& \-part_labels Whether to label individual undef (false) \& subparts. \& \& \-part_label_merge Whether to merge undef (false) \& adjacent subparts when \& labeling. \& \& \-connector Type of connector to none \& use to connect related \& features. Options are \& "solid," "hat", "dashed", \& "quill" and "none". \& \& \-all_callbacks Whether to invoke undef \& callbacks for autogenerated \& "track" and "group" glyphs \& \& \-subpart_callbacks Whether to invoke false \& callbacks for subparts of \& the glyph. \& \& \-box_subparts Return boxes around feature 0 \& subparts rather than around the \& feature itself. \& \& \-link, \-title, \-target \& These options are used when creating imagemaps \& for display on the web. See L. \& \& \-filter Select which features to \& display. Must be a CODE reference. .Ve .PP \&\fBSpecifying colors:\fR Colors can be expressed in either of two ways: as symbolic names such as \*(L"cyan\*(R", as HTML-style #RRGGBB triples, and r,g,b comma-separated numbers. The symbolic names are the 140 colors defined in the Netscape/Internet Explorer color cube, and can be retrieved using the Bio::Graphics::Panel\->\fBcolor_names()\fR method. .PP Transparent and semi-transparent colors can be specified using the following syntax: .PP .Vb 5 \& #RRGGBBAA \- red, green, blue and alpha \& r,g,b,a \- red, green, blue, alpha \& blue:alpha \- symbolic name and alpha \& rgb(r,g,b) \- CSS style rgb values \& rgba(r,g,b,a) \- CSS style rgba values .Ve .PP Alpha values can be specified as \s-1GD\s0 style integers ranging from 0 (opaque) to 127 (transparent), or as CSS-style floating point numbers ranging from 0.0 (transparent) through 1.0 (opaque). As a special case, a completely transparent color can be specified using the color named \*(L"transparent\*(R". In the \fBrgb()\fR and \fBrgba()\fR forms, red, green, blue values can be specified as percentages, as in rgb(100%,0%,50%); otherwise, the values are integers from 0 to 255. .PP In addition, the \-fgcolor and \-bgcolor options accept the special color names \*(L"featureScore\*(R" and \*(L"featureRGB\*(R". In the first case, Bio::Graphics will examine each feature in the track for a defined \&\*(L"score\*(R" tag (or the presence of a \fBscore()\fR method) with a numeric value ranging from 0\-1000. It will draw a grayscale color ranging from lightest (0) to darkest (1000). If the color is named \*(L"featureRGB\*(R", then Bio::Graphics will look for a tag named \*(L"\s-1RGB\*(R"\s0 and will use that as the color. .PP \&\fBForeground color:\fR The \-fgcolor option controls the foreground color, including the edges of boxes and the like. .PP \&\fBBackground color:\fR The \-bgcolor option controls the background used for filled boxes and other \*(L"solid\*(R" glyphs. The foreground color controls the color of lines and strings. The \-tkcolor argument controls the background color of the entire track. .PP \&\fBDefault opacity:\fRFor truecolor images, you can apply a default opacity value to both foreground and background colors by supplying a \fB\-opacity\fR argument. This is specified as a CSS-style floating point number from 0.0 to 1.0. If the color has an explicit alpha, then the default is ignored. .PP \&\fBTrack color:\fR The \-tkcolor option used to specify the background of the entire track. .PP \&\fBFont:\fR The \-font option controls which font will be used. If the Panel was created without passing a true value to \-truecolor, then only \s-1GD\s0 bitmapped fonts are available to you. These include \&'gdTinyFont', 'gdSmallFont', 'gdLargeFont', 'gdMediumBoldFont', and \&'gdGiantFont'. If the Panel was creaed using a truevalue for \&\-truecolor, then you can pass the name of any truetype font installed on the server system. Any of these formats will work: .PP .Vb 4 \& \-font => \*(AqTimes New Roman\*(Aq, # Times font, let the system pick size \& \-font => \*(AqTimes New Roman\-12\*(Aq # Times font, 12 points \& \-font => \*(AqTimes New Roman\-12:Italic\*(Aq # Times font, 12 points italic \& \-font => \*(AqTimes New Roman\-12:Bold\*(Aq # Times font, 12 points bold .Ve .PP \&\fBFont color:\fR The \-fontcolor option controls the color of primary text, such as labels .PP \&\fBSecondary Font color:\fR The \-font2color option controls the color of secondary text, such as descriptions. .PP \&\fBLabels:\fR The \-label argument controls whether or not the \s-1ID\s0 of the feature should be printed next to the feature. It is accepted by all glyphs. By default, the label is printed just above the glyph and left aligned with it. .PP \&\-label can be a constant string or a code reference. Values can be any of: .PP .Vb 2 \& \-label value Description \& \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& 0 Don\*(Aqt draw a label \& 1 Calculate a label based on primary tag of sequence \& "a string" Use "a string" as the label \& code ref Invoke the code reference to compute the label .Ve .PP A known bug with this naming scheme is that you can't label a feature with the string \*(L"1\*(R". To work around this, use \*(L"1 \*(R" (note the terminal space). .PP \&\fBDescriptions:\fR The \-description argument controls whether or not a brief description of the feature should be printed next to it. By default, the description is printed just below the glyph and left-aligned with it. A value of 0 will suppress the description. A value of 1 will \*(L"magically\*(R" look for tags of type \*(L"note\*(R" or \&\*(L"description\*(R" and draw them if found, otherwise the source tag, if any, will be displayed. A code reference will be invoked to calculate the description on the fly. Anything else will be treated as a string and used verbatim. .PP \&\fBConnectors:\fR A glyph can contain subglyphs, recursively. The top level glyph is the track, which contains one or more groups, which contain features, which contain subfeatures, and so forth. By default, the \*(L"group\*(R" glyph draws dotted lines between each of its subglyphs, the \*(L"segment\*(R" glyph draws a solid line between each of its subglyphs, and the \*(L"transcript\*(R" and \*(L"transcript2\*(R" glyphs draw hat-shaped lines between their subglyphs. All other glyphs do not connect their components. You can override this behavior by providing a \-connector option, to explicitly set the type of connector. Valid options are: .PP .Vb 5 \& "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. .Ve .PP The \fB\-connector_color\fR option controls the color of the connector, if any. .PP \&\fBCollision control:\fR The \fB\-bump\fR argument controls what happens when glyphs collide. By default, they will simply overlap (value 0). A \&\-bump value of +1 will cause overlapping glyphs to bump downwards until there is room for them. A \-bump value of \-1 will cause overlapping glyphs to bump upwards. You may also provide a \-bump value of +2 or \-2 to activate a very simple type of collision control in which each feature occupies its own line. This is useful for showing dense, nearly-full length features such as similarity hits. A bump of 3 or the string \*(L"fast\*(R" will turn on a faster collision-detection algorithm that only works properly with the default \*(L"left\*(R" sort order. .PP Finally, a bump value of \*(L"overlap\*(R" will cause features to overlap each other and to made partially translucent (the translucency can be controlled with the \-opacity setting). Features that are on opposite strands will bump, but those on the same strand will not. .PP The bump argument can also be a code reference; see below. .PP For convenience and backwards compatibility, if you specify a \-bump of 1 and use the default sort order, the faster algorithm will be used. .PP If you would like to see more horizontal whitespace between features that occupy the same line, you can specify it with the \fB\-hbumppad\fR option. Positive values increase the amount of whitespace between features. Negative values decrease the whitespace. .PP \&\fBKeys:\fR The \-key argument declares that the track is to be shown in a key appended to the bottom of the image. The key contains a picture of a glyph and a label describing what the glyph means. The label is specified in the argument to \-key. .PP \&\fBbox_subparts:\fR Ordinarily, when you invoke the \fBboxes()\fR methods to retrieve the rectangles surrounding the glyphs (which you need to do to create clickable imagemaps, for example), the rectangles will surround the top level features. If you wish for the rectangles to surround subpieces of the glyph, such as the exons in a transcript, set box_subparts to a true numeric value. The value you specify will control the number of levels of subfeatures that the boxes will descend into. For example, if using the \*(L"gene\*(R" glyph, set \&\-box_subparts to 2 to create boxes for the whole gene (level 0), the mRNAs (level 1) and the exons (level 2). .PP \&\fBpart_labels:\fR If set to true, each subpart of a multipart feature will be labeled with a number starting with 1 at the 5'\-most part. This is useful for counting exons. You can pass a callback to this argument; the part number and the total number of parts will be arguments three and four. For example, to label the exons as \*(L"exon 1\*(R", \&\*(L"exon 2\*(R" and so on: .PP .Vb 4 \& \-part_labels => sub { \& my ($feature,undef,$partno) = @_; \& return \*(Aqexon \*(Aq.($partno+1); \& } .Ve .PP The \fB\-label\fR argument must also be true. .PP \&\fBpart_labels_merge:\fR If true, changes the behavior of \-part_labels so that features that abut each other without a gap are treated as a single feature. Useful if you want to count the \s-1UTR\s0 and \s-1CDS\s0 segments of an exon as a single unit, and the default for transcript glyphs. .PP \&\fBstrand_arrow:\fR If set to true, some glyphs will indicate their strandedness, usually by drawing an arrow. For this to work, the Bio::SeqFeature must have a strand of +1 or \-1. The glyph will ignore this directive if the underlying feature has a strand of zero or undef. .PP \&\fBsort_order\fR: By default, features are drawn with a layout based only on the position of the feature, assuring a maximal \*(L"packing\*(R" of the glyphs when bumped. In some cases, however, it makes sense to display the glyphs sorted by score or some other comparison, e.g. such that more \&\*(L"important\*(R" features are nearer the top of the display, stacked above less important features. The \-sort_order option allows a few different built-in values for changing the default sort order (which is by \*(L"left\*(R" position): \*(L"low_score\*(R" (or \*(L"high_score\*(R") will cause features to be sorted from lowest to highest score (or vice versa). \&\*(L"left\*(R" (or \*(L"default\*(R") and \*(L"right\*(R" values will cause features to be sorted by their position in the sequence. \*(L"longest\*(R" (or \*(L"shortest\*(R") will cause the longest (or shortest) features to be sorted first, and \&\*(L"strand\*(R" will cause the features to be sorted by strand: \*(L"+1\*(R" (forward) then \*(L"0\*(R" (unknown, or \s-1NA\s0) then \*(L"\-1\*(R" (reverse). .PP In all cases, the \*(L"left\*(R" position will be used to break any ties. To break ties using another field, options may be strung together using a \&\*(L"|\*(R" character; e.g. \*(L"strand|low_score|right\*(R" would cause the features to be sorted first by strand, then score (lowest to highest), then by \&\*(L"right\*(R" position in the sequence. .PP Finally, a subroutine coderef with a $$ prototype can be provided. It will receive two \fBglyph\fR as arguments and should return \-1, 0 or 1 (see Perl's \fBsort()\fR function for more information). For example, to sort a set of database search hits by bits (stored in the features' \&\*(L"score\*(R" fields), scaled by the log of the alignment length (with \&\*(L"start\*(R" position breaking any ties): .PP .Vb 10 \& 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 ) \& } .Ve .PP It is important to remember to use the $$ prototype as shown in the example. Otherwise Bio::Graphics will quit with an exception. The arguments are subclasses of Bio::Graphics::Glyph, not the features themselves. While glyphs implement some, but not all, of the feature methods, to be safe call the two glyphs' \fBfeature()\fR methods in order to convert them into the actual features. .PP The '\-always_sort' option, if true, will sort features even if bumping is turned off. This is useful if you would like 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. .PP \&\fB\-feature_limit\fR: When this option is set to a non-zero value, calls to a track's \fBadd_feature()\fR method will maintain a count of features added to a 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 track's \&\fBfeature_count()\fR method. .PP \&\fB\-bump_limit\fR: When bumping is chosen, colliding features will ordinarily move upward or downward without limit. When many features collide, this can lead to excessively high images. You can limit the number of levels that features will bump by providing a numeric \&\fBbump_limit\fR option. After the limit is hit, features will pile up on top of each other, usually as a band at the bottom of the track. .PP The \fB\-filter\fR option, which must be a \s-1CODE\s0 reference, will be invoked once for each feature prior to rendering it. The coderef will receive the feature as its single option and should return true if the feature is to be shown and false otherwise. .SS "Options and Callbacks" .IX Subsection "Options and Callbacks" Instead of providing a constant value to an option, you may subsitute a code reference. This code reference will be called every time the panel needs to configure a glyph. The callback will be called with three arguments like this: .PP .Vb 5 \& sub callback { \& my ($feature,$option_name,$part_no,$total_parts,$glyph) = @_; \& # do something which results in $option_value being set \& return $option_value; \& } .Ve .PP The five arguments are \f(CW$feature\fR, a reference to the IO::SeqFeatureI object, \f(CW$option_name\fR, the name of the option to configure, \&\f(CW$part_no\fR, an integer index indicating which subpart of the feature is being drawn, \f(CW$total_parts\fR, an integer indicating the total number of subfeatures in the feature, and finally \f(CW$glyph\fR, the Glyph object itself. The latter fields are useful in the case of treating the first or last subfeature differently, such as using a different color for the terminal exon of a gene. Usually you will only need to examine the first argument. This example shows a callback examining the \fBscore()\fR attribute of a feature (possibly a \s-1BLAST\s0 hit) and return the color \*(L"red\*(R" for high-scoring features, and \*(L"green\*(R" for low-scoring features: .PP .Vb 8 \& sub callback { \& my $feature = shift; \& if ($feature\->score > 90) { \& return \*(Aqred\*(Aq; \& else { \& return \*(Aqgreen\*(Aq; \& } \& } .Ve .PP The callback should return a string indicating the desired value of the option. To tell the panel to use the default value for this option, return the string \*(L"*default*\*(R". .PP The callback for \-grid is slightly different because at the time this option is needed there is no glyph defined. In this case, the callback will get two arguments: the feature and the panel object: .PP .Vb 5 \& \-glyph => sub { \& my ($feature,$panel) = @_; \& return \*(Aqgene\*(Aq if $panel\->length < 10_000; \& return \*(Aqbox\*(Aq; \& } .Ve .PP When you install a callback for a feature that contains subparts, the callback will be invoked first for the top-level feature, and then for each of its subparts (recursively). You should make sure to examine the feature's type to determine whether the option is appropriate. .PP Also be aware that some options are only called for subfeatures. For example, when using multi-segmented features, the \*(L"bgcolor\*(R" and \&\*(L"fgcolor\*(R" options apply to the subfeatures and not to the whole feature; therefore the corresponding callbacks will only be invoked for the subfeatures and not for the top-level feature. To get information that applies to the top-level feature, use the glyph's \&\fBparent_feature()\fR method. This returns: .PP .Vb 4 \& * the parent if called with no arguments or with an argument of (1) \& * the parent\*(Aqs parent if called with an argument of (2) \& * the parent\*(Aqs parent\*(Aqs parent if called with an argument of (3) \& * etc. .Ve .PP The general way to take advantage of this feature is: .PP .Vb 3 \& sub callback { \& my ($feature,$option_name,$part_no,$total_parts,$glyph) = @_; \& my $parent = $glyph\->parent_feature(); \& \& # do something which results in $option_value being set \& return $option_value; \& } .Ve .PP or, more concisely: .PP .Vb 4 \& sub callback { \& my $feature = shift; # first argument \& my $glyph = pop; # last argument \& my $parent = $glyph\->parent_feature(); \& \& # do something which results in $option_value being set \& return $option_value; \& } .Ve .PP Some glyphs deliberately disable recursion into subparts. The \&\*(L"track\*(R", \*(L"group\*(R", \*(L"transcript\*(R", \*(L"transcript2\*(R" and \*(L"segments\*(R" glyphs selectively disable the \-bump, \-label and \-description options. This is to avoid, for example, a label being attached to each exon in a transcript, or the various segments of a gapped alignment bumping each other. You can override this behavior and force your callback to be invoked by providing \fBadd_track()\fR with a true \fB\-all_callbacks\fR argument. In this case, you must be prepared to handle configuring options for the \*(L"group\*(R" and \*(L"track\*(R" glyphs. .PP In particular, this means that in order to control the \-bump option with a callback, you should specify \-all_callbacks=>1, and turn on bumping when the callback is in the track or group glyphs. .PP The \-subpart_callbacks options is similar, except that when this is set to true callbacks are invoked for the main glyph and its subparts. This option only affects the \-label and \-description options. .SS "\s-1ACCESSORS\s0" .IX Subsection "ACCESSORS" The following accessor methods provide access to various attributes of the panel object. Called with no arguments, they each return the current value of the attribute. Called with a single argument, they set the attribute and return its previous value. .PP Note that in most cases you must change attributes prior to invoking \&\fBgd()\fR, \fBpng()\fR or \fBboxes()\fR. These three methods all invoke an internal \&\fBlayout()\fR method which places the tracks and the glyphs within them, and then caches the result. .PP .Vb 2 \& Accessor Name Description \& \-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& width() Get/set width of panel \& spacing() Get/set spacing between tracks \& key_spacing() Get/set spacing between keys \& length() Get/set length of segment (bp) \& flip() Get/set coordinate flipping \& pad_top() Get/set top padding \& pad_left() Get/set left padding \& pad_bottom() Get/set bottom padding \& pad_right() Get/set right padding \& start() Get the start of the sequence (bp; read only) \& end() Get the end of the sequence (bp; read only) \& left() Get the left side of the drawing area (pixels; read only) \& right() Get the right side of the drawing area (pixels; read only) .Ve .SS "\s-1COLOR METHODS\s0" .IX Subsection "COLOR METHODS" The following methods are used internally, but may be useful for those implementing new glyph types. .ie n .IP "@names = Bio::Graphics::Panel\->color_names" 4 .el .IP "\f(CW@names\fR = Bio::Graphics::Panel\->color_names" 4 .IX Item "@names = Bio::Graphics::Panel->color_names" Return the symbolic names of the colors recognized by the panel object. In a scalar context, returns an array reference. .IP "($red,$green,$blue) = Bio::Graphics::Panel\->color_name_to_rgb($color)" 4 .IX Item "($red,$green,$blue) = Bio::Graphics::Panel->color_name_to_rgb($color)" Given a symbolic color name, returns the red, green, blue components of the color. In a scalar context, returns an array reference to the rgb triplet. Returns undef for an invalid color name. .ie n .IP "@rgb = $panel\->rgb($index)" 4 .el .IP "\f(CW@rgb\fR = \f(CW$panel\fR\->rgb($index)" 4 .IX Item "@rgb = $panel->rgb($index)" Given a \s-1GD\s0 color index (between 0 and 140), returns the \s-1RGB\s0 triplet corresponding to this index. This method is only useful within a glyph's \fBdraw()\fR routine, after the panel has allocated a GD::Image and is populating it. .ie n .IP "$index = $panel\->translate_color($color)" 4 .el .IP "\f(CW$index\fR = \f(CW$panel\fR\->translate_color($color)" 4 .IX Item "$index = $panel->translate_color($color)" Given a color, returns the GD::Image index. The color may be symbolic, such as \*(L"turquoise\*(R", or a #RRGGBB triple, as in #F0E0A8. This method is only useful within a glyph's \fBdraw()\fR routine, after the panel has allocated a GD::Image and is populating it. .ie n .IP "$panel\->set_pen($width,$color)" 4 .el .IP "\f(CW$panel\fR\->set_pen($width,$color)" 4 .IX Item "$panel->set_pen($width,$color)" Changes the width and color of the \s-1GD\s0 drawing pen to the values indicated. This is called automatically by the GlyphFactory \fBfgcolor()\fR method. It returns the \s-1GD\s0 value gdBrushed, which should be used for drawing. .SS "Creating Imagemaps" .IX Subsection "Creating Imagemaps" You may wish to use Bio::Graphics to create clickable imagemaps for display on the web. The main method for achieving this is \&\fBimage_and_map()\fR. Under special circumstances you may instead wish to call either or both of \fBcreate_web_image()\fR and \fBcreate_web_map()\fR. .PP Here is a synopsis of how to use \fBimage_and_map()\fR in a \s-1CGI\s0 script, using \s-1CGI\s0.pm calls to provide the \s-1HTML\s0 scaffolding: .PP .Vb 1 \& print h2(\*(AqMy Genome\*(Aq); \& \& my ($url,$map,$mapname) = \& $panel\->image_and_map(\-root => \*(Aq/var/www/html\*(Aq, \& \-url => \*(Aq/tmpimages\*(Aq, \& \-link => \*(Aqhttp://www.google.com/search?q=$name\*(Aq); \& \& print img({\-src=>$url,\-usemap=>"#$mapname"}); \& \& print $map; .Ve .PP We call \fBimage_and_map()\fR with various arguments (described below) to generate a three element list consisting of the \s-1URL\s0 at which the image can be accessed, an \s-1HTML\s0 fragment containing the clickable imagemap data, and the name of the map. We print out an tag that uses the \s-1URL\s0 of the map as its src attribute and the name of the map as the value of its usemap attribute. It is important to note that we must put a \*(L"#\*(R" in front of the name of the map in order to indicate that the map can be found in the same document as the tag. Lastly, we print out the map itself. .ie n .IP "($url,$map,$mapname) = $panel\->image_and_map(@options)" 4 .el .IP "($url,$map,$mapname) = \f(CW$panel\fR\->image_and_map(@options)" 4 .IX Item "($url,$map,$mapname) = $panel->image_and_map(@options)" Create the image in a web-accessible directory and return its \s-1URL,\s0 its clickable imagemap, and the name of the imagemap. The following options are recognized: .Sp .Vb 2 \& Option Description \& \-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& \-url The URL to store the image at. \& \& \& \-root The directory path that should be appended to the \& start of \-url in order to obtain a physical \& directory path. \& \-link A string pattern or coderef that will be used to \& generate the outgoing hypertext links for the imagemap. \& \& \-title A string pattern or coderef that will be used to \& generate the "title" tags of each element in the imagemap \& (these appear as popup hint boxes in certain browsers). \& \& \-target A string pattern or coderef that will be used to \& generate the window target for each element. This can \& be used to pop up a new window when the user clicks on \& an element. \& \& \-mapname The name to use for the EmapE tag. If not provided, \& a unique one will be autogenerated for you. .Ve .Sp This method returns a three element list consisting of the \s-1URL\s0 at which the image has been written to, the imagemap \s-1HTML,\s0 and the name of the map. Usually you will incorporate this information into an \&\s-1HTML\s0 document like so: .Sp .Vb 4 \& my ($url,$map,$mapname) = \& $panel\->image_and_map(\-link=>\*(Aqhttp://www.google.com/search?q=$name\*(Aq); \& print qq(),"\en"; \& print $map,"\en"; .Ve .ie n .IP "$url = $panel\->create_web_image($url,$root)" 4 .el .IP "\f(CW$url\fR = \f(CW$panel\fR\->create_web_image($url,$root)" 4 .IX Item "$url = $panel->create_web_image($url,$root)" Create the image, write it into the directory indicated by concatenating \f(CW$root\fR and \f(CW$url\fR (i.e. \*(L"$root/$url\*(R"), and return \f(CW$url\fR. .ie n .IP "$map = $panel\->create_web_map('mapname',$linkrule,$titlerule,$targetrule)" 4 .el .IP "\f(CW$map\fR = \f(CW$panel\fR\->create_web_map('mapname',$linkrule,$titlerule,$targetrule)" 4 .IX Item "$map = $panel->create_web_map('mapname',$linkrule,$titlerule,$targetrule)" Create a clickable imagemap named \*(L"mapname\*(R" using the indicated rules to generate the hypertext links, the element titles, and the window targets for the graphical elements. Return the \s-1HTML\s0 for the map, including the enclosing tag itself. .PP To use this method effectively, you will need a web server and an image directory in the document tree that is writable by the web server user. For example, if your web server's document root is located at /var/www/html, you might want to create a directory named \&\*(L"tmpimages\*(R" for this purpose: .PP .Vb 2 \& mkdir /var/www/html/tmpimages \& chmod 1777 /var/www/html/tmpimages .Ve .PP The 1777 privilege will allow anyone to create files and subdirectories in this directory, but only the owner of the file will be able to delete it. .PP When you call \fBimage_and_map()\fR, you must provide it with two vital pieces of information: the \s-1URL\s0 of the image directory and the physical location of the web server's document tree. In our example, you would call: .PP .Vb 1 \& $panel\->image_and_map(\-root => \*(Aq/var/www/html\*(Aq,\-url=>\*(Aq/tmpimages\*(Aq); .Ve .PP If you are working with virtual hosts, you might wish to provide the hostname:portnumber part of the \s-1URL.\s0 This will work just as well: .PP .Vb 2 \& $panel\->image_and_map(\-root => \*(Aq/var/www/html\*(Aq, \& \-url => \*(Aqhttp://myhost.com:8080/tmpimages\*(Aq); .Ve .PP If you do not provide the \-root argument, the method will try to figure it out from the \s-1DOCUMENT_ROOT\s0 environment variable. If you do not provide the \-url argument, the method will assume \*(L"/tmp\*(R". .PP During execution, the \fBimage_and_map()\fR method will generate a unique name for the image using the Digest::MD5 module. You can get this module on \s-1CPAN\s0 and it \fBmust\fR be installed in order to use \&\fBimage_and_map()\fR. The imagename will be a long hexadecimal string such as \*(L"e7457643f12d413f20843d4030c197c6.png\*(R". Its \s-1URL\s0 will be /tmpimages/e7457643f12d413f20843d4030c197c6.png, and its physical path will be /var/www/html/tmpimages/e7457643f12d413f20843d4030c197c6.png .PP In addition to providing directory information, you must also tell \&\fBimage_and_map()\fR how to create outgoing links for each graphical feature, and, optionally, how to create the \*(L"hover title\*(R" (the popup yellow box displayed by most modern browsers), and the name of the window or frame to link to when the user clicks on it. .PP There are three ways to specify the link destination: .IP "1." 4 By configuring one or more tracks with a \-link argument. .IP "2." 4 By configuring the panel with a \-link argument. .IP "3." 4 By passing a \-link argument in the call to \fBimage_and_map()\fR. .PP The \-link argument can be either a string or a coderef. If you pass a string, it will be interpreted as a \s-1URL\s0 pattern containing runtime variables. These variables begin with a dollar sign ($), and are replaced at run time with the information relating to the selected annotation. Recognized variables include: .PP .Vb 10 \& $name The feature\*(Aqs name (display name) \& $id The feature\*(Aqs id (eg, PK from a database) \& $class The feature\*(Aqs class (group class) \& $method The feature\*(Aqs method (same as primary tag) \& $source The feature\*(Aqs source \& $ref The name of the sequence segment (chromosome, contig) \& on which this feature is located \& $description The feature\*(Aqs description (notes) \& $start The start position of this feature, relative to $ref \& $end The end position of this feature, relative to $ref \& $length Length of this feature \& $segstart The left end of $ref displayed in the detailed view \& $segend The right end of $ref displayed in the detailed view .Ve .PP For example, to link each feature to a Google search on the feature's description, use the argument: .PP .Vb 1 \& \-link => \*(Aqhttp://www.google.com/search?q=$description\*(Aq .Ve .PP Be sure to use single quotes around the pattern, or Perl will attempt to perform variable interpretation before \fBimage_and_map()\fR has a chance to work on it. .PP You may also pass a code reference to \-link, in which case the code will be called every time a \s-1URL\s0 needs to be generated for the imagemap. The subroutine will be called with two arguments, the feature and the Bio::Graphics::Panel object, and it should return the \&\s-1URL\s0 to link to, or an empty string if a link is not desired. Here is a simple example: .PP .Vb 9 \& \-link => sub { \& my ($feature,$panel) = @_; \& my $type = $feature\->primary_tag; \& my $name = $feature\->display_name; \& if ($primary_tag eq \*(Aqclone\*(Aq) { \& return "http://www.google.com/search?q=$name"; \& } else { \& return "http://www.yahoo.com/search?p=$name"; \& } .Ve .PP The \-link argument cascades. \fBimage_and_map()\fR will first look for a \&\-link option in the track configuration, and if that's not found, it will look in the Panel configuration (created during Bio::Graphics::Panel\->new). If no \-link configuration option is found in either location, then \fBimage_and_map()\fR will use the value of \-link passed in its argument list, if any. .PP The \-title and \-target options behave in a similar manner to \-link. \&\-title is used to assign each feature \*(L"title\*(R" and \*(L"alt\*(R" attributes. The \*(L"title\*(R" attribute is used by many browsers to create a popup hints box when the mouse hovers over the feature's glyph for a preset length of time, while the \*(L"alt\*(R" attribute is used to create navigable menu items for the visually impaired. As with \-link, you can set the title by passing either a substitution pattern or a code ref, and the \-title option can be set in the track, the panel, or the method call itself in that order of priority. .PP If not provided, \fBimage_and_map()\fR will autogenerate its own title in the form \*(L" :start..end\*(R". .PP The \-target option can be used to specify the window or frame that clicked features will link to. By default, when the user clicks on a feature, the loaded \s-1URL\s0 will replace the current page. You can modify this by providing \-target with the name of a preexisting or new window name in order to create effects like popup windows, multiple frames, popunders and the like. The value of \-target follows the same rules as \-title and \-link, including variable substitution and the use of code refs. .PP \&\s-1NOTE:\s0 Each time you call \fBimage_and_map()\fR it will generate a new image file. Images that are identical to an earlier one will reuse the same name, but those that are different, even by one pixel, will result in the generation of a new image. If you have limited disk space, you might wish to check the images directory periodically and remove those that have not been accessed recently. The following cron script will remove image files that haven't been accessed in more than 20 days. .PP 30 2 * * * find /var/www/html/tmpimages \-type f \-atime +20 \-exec rm {} \e; .SH "BUGS" .IX Header "BUGS" Please report them. .SH "SEE ALSO" .IX Header "SEE ALSO" 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::line, Bio::Graphics::Glyph::pinsertion, Bio::Graphics::Glyph::primers, Bio::Graphics::Glyph::rndrect, Bio::Graphics::Glyph::segments, Bio::Graphics::Glyph::redgreen_box, 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::Graphics::Glyph::xyplot, Bio::Graphics::Glyph::whiskerplot, Bio::SeqI, Bio::SeqFeatureI, Bio::Das, \&\s-1GD\s0 \&\s-1GD::SVG\s0 glyph_help.pl .SH "AUTHOR" .IX Header "AUTHOR" Lincoln Stein .PP Copyright (c) 2001 Cold Spring Harbor Laboratory .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \s-1DISCLAIMER\s0.txt for disclaimers of warranty.