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

✨ NAME ✨

Bio::G...kedplot — the stackedplot glyph 💖 (and yeah bestie, the manual page for it is Bio::G...kedplot(3pm), that's the one you're reading rn)

---

🦋 SYNOPSIS 🦋

okay so literally just go look at these two:

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

that's it, that's the synopsis 🫶

---

💖 DESCRIPTION 💖

so the stackedplot glyph is the one you reach for when you wanna draw quantitative feature data as a stacked column plot ✨. it's giving bar chart but make it genomic.

now here's the thing that makes it different from xyplot, and this is important bestie: the plot applies to a single top level feature, not a group of subfeatures. completely different vibe. periodt.

and where does the data even come from?? it's derived from an attribute called data_series. iconic.

🎀 how the data is shaped

the data to be graphed is represented as a list of arrays, like this:

(
[1, 2, 8],
[6, 1, 1],
[10,8, 0],
[1, 1, 1],
)

so each array in that list = one column in the stacked plot 🌈. and the values inside it become the subdivisions of the column. so in this example there are four columns, and each of those columns has three subdivisions. math is mathing 💅

you can also add labels to the columns and change the colors of the subdivisions. obsessed.

🌸 how to actually assign data to a feature

you can add a series tag, like so:

$snp1    = Bio::SeqFeature::Generic ->new (-start     => 500,-end=>501,
                                           -display_name =>'example',
                                           -tag=> { series => [
                                                            [10,20,30],
                                                            [30,30,0],
                                                            [5,45,10],
                                                            [5,45,10],
                                                            [5,45,10],
                                                            [50,0,50],
                                                           ],
                                                    }
                                              );

bestie listen — the series tag must consist of an array of arrays. no cap. don't try to be cute and pass it something else.

💜 if you're on gff3

you can load a database with data that looks like this:

chr1 test feature 1 1000 . . . series=10 20 30;series=30 30 0;series=5 45 10...

🧚 if you're on gff2

then you can load a database with data that looks like this:

chr1 test feature 1 1000 . . . series 10 20 30; series 30 30 0 series 5 45 10...

⭐ or, the callback route

you can also pass a callback to the -series option, which is lowkey the most flexible option:

$panel->add_track(\@data,
                 -glyph     => 'stackedplot',
                 -series       => sub {
                                 my $feature = shift;
                            return [
                               [10,20,30],
                               [30,30,0],
                               [5,45,10],
                           ]
                         }
                );

---

✨ OPTIONS ✨

🌈 the standard ones (every Glyph has these)

these options are standard among all Glyphs, fr fr. 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
• -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)

🫶 and the glyph-specific ones

okay so on top of all that, the alignment glyph recognizes all the options of the xyplot glyph, plus these extra glyph-specific options:

• -fixed_gap — Vertical distance between the rectangle that shows the start:end range of the feature and the fixed width stacked plot. default: 8
• -series_colors — A list giving a series of color names for the data series (the values inside each stacked column). default: red,blue,green,orange,brown,grey,black
• -column_labels — A list of labels to print underneath each column. default: -none-
• -column_width — The width of each column. default: 8
• -column_spacing — Spacing between each column. default: 2
• -min_score — Minimum score for the sum of the members of each data series. default: 0.0
• -max_score — Maximum score for the sum of the members of each data series. default: 1.0
• -scale_font — Font to use for the scale. default: gdTinyFont
• -column_font — Font to use for the column labels. default: gdSmallFont
• -draw_scale — Whether to draw a scale to right of the columns. default: true

⚠️ important note, don't skip this one ⚠️ -min_score and -max_score represent the minimum and maximum SUM of all the values in the data series. so like, if your largest column contains the series (10,20,30), then the -max_score is 60. yes you have to do the addition yourself. it's giving homework but it's fine 💅

---

🌸 EXAMPLE 🌸

to understand how this glyph works, try running and modifying the following example (go on, poke at it, it's fun):

#!/usr/bin/perl

use strict;
use warnings;

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

my $segment  = Bio::Graphics::Feature->new(-start=>1,-end=>700);

my $snp1     = Bio::SeqFeature::Generic ->new (-start     => 500,-end=>590,
                                               -display_name =>'fred',
                                               -tag=> { series => [
                                                                    [10,20,30],
                                                                    [30,30,0],
                                                                    [5,45,10],
                                                                    [5,45,10],
                                                                    [5,45,10],
                                                                    [50,0,50],
                                                                   ],
                                                     },
                                               -source=>'A test',
                                               );

my $snp2     = Bio::SeqFeature::Generic->new(-start     => 300,
                                             -end       => 301,
                                             -display_name  => 'rs12345',
                                             -tag=> {
                                                    series => [
                                                                    [30,20,10 ],
                                                                    [80,10,10 ],
                                                              ],
                                                   },
                                             -source=>'Another test',
                                           );

my $panel = Bio::Graphics::Panel->new(-segment=>$segment,-width=>800);

$panel->add_track($segment,-glyph=>'arrow',-double=>1,-tick=>2);
$panel->add_track([$snp1,$snp2],
                  -height    => 50,
                  -glyph     => 'stackedplot',
                  -fixed_gap => 12,
                  -series_colors    => [qw(red blue lavender)],
                  -column_labels => [qw(a b c d e f g)],
                  -min_score => 0,
                  -max_score => 100,
                  -column_width => 8,
                  -column_font  => 'gdMediumBoldFont',
                  -scale_font   => 'gdTinyFont',
                  -label    => 1,
                  -description=>1,
                 );
print $panel->png;

---

💀 BUGS 💀

Please report them. (that's it. that's the whole section. they're out there. go tell someone 😭)

---

👑 SEE ALSO 👑

go read these next bestie, they're all connected:

• 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> — shoutout to the icon 👑

Copyright (c) 2006 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.

---

okay and that's the whole page bestie, you made it to the end 🫶 this was perl v5.30.0, dated 2019-11-25, and the page you just read is Bio::G...kedplot(3pm). go forth and stack those plots, you absolute main character 💖✨🌸