NAME

Tk::ForDummies::Graph::Boxplots - Extension of Canvas widget to create boxplots chart.

SYNOPSIS

#!/usr/bin/perl
use strict;
use warnings;
use Tk;
use Tk::ForDummies::Graph::Boxplots;

my $mw = new MainWindow(
  -title      => 'Tk::ForDummies::Graph::Boxplots example',
  -background => 'white',
);

my $GraphDummies = $mw->Boxplots(
  -title      => 'My chart title',
  -xlabel     => 'X Label',
  -ylabel     => 'Y Label',
  -background => 'snow',
)->pack(qw / -fill both -expand 1 /);

my $one   = [ 210 .. 275 ];
my $two   = [ 180, 190, 200, 220, 235, 245 ];
my $three = [ 40, 140 .. 150, 160 .. 180, 250 ];
my $four  = [ 100 .. 125, 136 .. 140 ];
my $five  = [ 10 .. 50, 100, 180 ];

my @data = (
  [ "1st", "2nd", "3rd",  "4th", "5th" ],
  [ $one,  $two,  $three, $four, $five ],
  [ [-25, 1..15], [-45, 25..45, 100], [70, 42..125], undef, [180..250] ],
  # ...
);

# Add a legend to the chart
my @Legends = ( 'legend 1', 'legend 2' );
$GraphDummies->set_legend(
  -title       => "Title legend",
  -data        => \@Legends,
);

# Add help identification
$GraphDummies->set_balloon();

# Create the chart
$GraphDummies->plot( \@data );

MainLoop();

DESCRIPTION

Tk::ForDummies::Graph::Boxplots is an extension of the Canvas widget. It is an easy way to build interactive boxplots (also known as a box-and-whisker diagram or plot) chart into your Perl Tk widget. The module is written entirely in Perl/Tk.

You can change the color, font of title, labels (x and y) of the chart. You can set an interactive legend. The axes can be automatically scaled or set by the code.

When the mouse cursor passes over a boxplot, its outlier or its entry in the legend, the boxplot and its entry will be turned to a color (that you can change) to help identify it.

You can use 3 methods to zoom (vertically, horizontally or both).

STANDARD OPTIONS

-background -borderwidth -closeenough -confine -cursor -height -highlightbackground -highlightcolor -highlightthickness -insertbackground -insertborderwidth -insertofftime -insertontime -insertwidth -relief -scrollregion -selectbackground -selectborderwidth -selectforeground -takefocus -width -xscrollcommand -xscrollincrement -yscrollcommand -yscrollincrement

Name: Spacingbar

Class: SpacingBar

Switch: -spacingbar

Set this to 1 to display remove space between each bar.

-spacingbar => 0, # 0 or 1

Default : 1

Many options allow you to configure your chart as you want. The default configuration is already OK, but you can change it. these are the same options as Tk::ForDummies::Graph::Lines module

Name: Title

Class: Title

Switch: -title

Title of your graph.

-title => "My graph title",

Default : undef

Name: Titleposition

Class: TitlePosition

Switch: -titleposition

Position of title : center, left or right

-titleposition => 'left',

Default : center

Name: Titlecolor

Class: TitleColor

Switch: -titlecolor

Title color of your graph.

-titlecolor => "red",

Default : black

Name: Titlefont

Class: TitleFont

Switch: -titlefont

Set the font for the title text. See also textfont option.

-titlefont => "Times 15 {normal}",

Default : {Times} 12 {bold}

Name: Titleheight

Class: TitleHeight

Switch: -titleheight

Height for title graph space.

-titleheight => 100,

Default : 40

Name: Xlabel

Class: XLabel

Switch: -xlabel

The label to be printed just below the x axis.

-xlabel => "X label",

Default : undef

Name: Xlabelcolor

Class: XLabelColor

Switch: -xlabelcolor

Set x label color. See also textcolor option.

-xlabelcolor => "red",

Default : black

Name: Xlabelfont

Class: XLabelFont

Switch: -xlabelfont

Set the font for the x label text. See also textfont option.

-xlabelfont => "Times 15 {normal}",

Default : {Times} 10 {bold}

Name: Xlabelheight

Class: XLabelHeight

Switch: -xlabelheight

Height for x label space.

-xlabelheight => 50,

Default : 30

Name: Xlabelskip

Class: XLabelSkip

Switch: -xlabelskip

Print every xlabelskip number under the tick on the x axis. If you have a dataset wich contain many points, the tick and x values will be overwrite on the chart. This option can help you to clarify your chart. Eg:

["leg1", "leg2", ..."leg1000", "data1", ... "data1000"] => 2000 ticks and text values on x axis.
-xlabelskip => 1 => ["leg1", "leg3", "leg5", ...] => 1000 ticks will be display.

See also xvaluesregex option.

-xlabelskip => 2,

Default : 0

Name: Xvaluecolor

Class: XValueColor

Switch: -xvaluecolor

Set x values colors. See also textcolor option.

-xvaluecolor => "red",

Default : black

Name: Xvaluespace

Class: XValueSpace

Switch: -xvaluespace

Width for x values space.

-xvaluespace => 50,

Default : 30

Name: Xvalueview

Class: XvalueView

Switch: -xvalueview

View values on x axis.

-xvalueview => 0, # 0 or 1

Default : 1

Name: Xvaluesregex

Class: XValuesRegex

Switch: -xvaluesregex

View the x values which will match with regex. It allows you to display tick on x axis and values that you want. You can combine it with -xlabelskip to perform what you want to display if you have many dataset.

...
["leg1", "leg2", "data1", "data2", "symb1", "symb2"]
...

-xvaluesregex => qr/leg/i,

On the graph, just leg1 and leg2 will be display.

Default : qr/.+/

Name: Ylabel

Class: YLabel

Switch: -ylabel

The labels to be printed next to y axis.

-ylabel => "Y label",

Default : undef

Name: Ylabelcolor

Class: YLabelColor

Switch: -ylabelcolor

Set the color of y label. See also textcolor option.

-ylabelcolor => 'red',

Default : black

Name: Ylabelfont

Class: YLabelFont

Switch: -ylabelfont

Set the font for the y label text. See also textfont option.

-ylabelfont => "Times 15 {normal}",

Default : {Times} 10 {bold}

Name: Ylabelwidth

Class: YLabelWidth

Switch: -ylabelwidth

Width of space for y label.

-ylabelwidth => 30,

Default : 5

Name: Yvaluecolor

Class: YValueColor

Switch: -yvaluecolor

Set the color of y values. See also valuecolor option.

-yvaluecolor => "red",

Default : black

Name: Yvalueview

Class: YvalueView

Switch: -yvalueview

View values on y axis.

-yvalueview => 0, # 0 or 1

Default : 1

Name: Labelscolor

Class: LabelsColor

Switch: -labelscolor

Combine xlabelcolor and ylabelcolor options. See also textcolor option.

-labelscolor => "red",

Default : undef

Name: Valuescolor

Class: ValuesColor

Switch: -valuescolor

Set the color of x, y values in axis. It combines xvaluecolor and yvaluecolor options.

-valuescolor => "red",

Default : undef

Name: Textcolor

Class: TextColor

Switch: -textcolor

Set the color of x, y labels and title text. It combines titlecolor, xlabelcolor and ylabelcolor options.

-textcolor => "red",

Default : undef

Name: Textfont

Class: TextFont

Switch: -textfont

Set the font of x, y labels and title text. It combines titlefont, xlabelfont and ylabelfont options.

-textfont => "Times 15 {normal}",

Default : undef

Name: Longticks

Class: LongTicks

Switch: -longticks

If long_ticks is a true value, ticks will be drawn the same length as the axes.

-longticks => 1, #  0 or 1

Default : 0

Name: Boxaxis

Class: BoxAxis

Switch: -boxaxis

Draw the axes as a box.

-boxaxis => 0, #  0 or 1

Default : 1

Name: Noaxis

Class: NoAxis

Switch: -noaxis

Hide the axis with ticks and values ticks.

-noaxis => 1, # 0 or 1

Default : 0

Name: Zeroaxis

Class: ZeroAxis

Switch: -zeroaxis

If set to a true value, the axis for y values will only be drawn. This might be useful in case your graph contains negative values, but you want it to be clear where the zero value is (see also zeroaxisonly and boxaxis).

-zeroaxis => 1, # 0 or 1

Default : 0

Name: Zeroaxisonly

Class: ZeroAxisOnly

Switch: -zeroaxisonly

If set to a true value, the zero x axis will be drawn and no axis at the bottom of the graph will be drawn. The labels for X values will be placed on the zero x axis. This works if there is at least one negative value in dataset.

-zeroaxisonly => 1, # 0 or 1

Default : 0

Name: Xtickheight

Class: XTickHeight

Switch: -xtickheight

Set height of all x ticks.

-xtickheight => 10,

Default : 5

Name: Xtickview

Class: XTickView

Switch: -xtickview

View x ticks of graph.

-xtickview => 0, # 0 or 1

Default : 1

Name: Yticknumber

Class: YTickNumber

Switch: -yticknumber

Number of ticks to print for the Y axis.

-yticknumber => 10,

Default : 4

Name: Ytickwidth

Class: YtickWidth

Switch: -ytickwidth

Set width of all y ticks.

-ytickwidth => 10,

Default : 5

Name: Ytickview

Class: YTickView

Switch: -ytickview

View y ticks of graph.

-ytickview => 0, # 0 or 1

Default : 1

Name: Alltickview

Class: AllTickView

Switch: -alltickview

View all ticks of graph. Combines xtickview and ytickview options;

-alltickview => 0, # 0 or 1

Default : undef

Name: Linewidth

Class: LineWidth

Switch: -linewidth

Set width of all lines graph of dataset.

-linewidth => 10,

Default : 1

Name: Colordata

Class: ColorData

Switch: -colordata

This controls the colors of the lines. This should be a reference to an array of color names.

-colordata => [ qw(green pink blue cyan) ],

Default :

[ 'red',     'green',   'blue',    'yellow',  'purple',  'cyan',
  '#996600', '#99A6CC', '#669933', '#929292', '#006600', '#FFE100',
  '#00A6FF', '#009060', '#B000E0', '#A08000', 'orange',  'brown',
  'black',   '#FFCCFF', '#99CCFF', '#FF00CC', '#FF8000', '#006090',
],

The default array contains 24 colors. If you have more than 24 samples, the next line will have the color of the first array case (red).

The Canvas method creates a widget object. This object supports the configure and cget methods described in Tk::options which can be used to enquire and modify the options described above.

add_data

$GraphDummies->add_data(\@NewData, ?$legend): This method allows you to add data in your chart. If you have already plot data using plot method and if you want to add new data, you can use this method. Your chart will be updade.

Data array reference

Fill an array of arrays with the values of the datasets (\@data). Make sure that every array has the same size, otherwise Tk::ForDummies::Graph::Lines will complain and refuse to compile the graph.
```
my $one     = [ 210 .. 275 ];
my $two     = [ 180, 190, 200, 220, 235, 245 ];
my $three   = [ 40, 140 .. 150, 160 .. 180, 250 ];
my $four    = [ 100 .. 125, 136 .. 140 ];
my $five    = [ 10 .. 50, 100, 180 ];
my @NewData = ( $one, $two, $three, $four, $five );
$GraphDummies->add_data( \@NewData, 'new legend' );
```
If your last chart has a legend, you have to add a legend entry for the new dataset. Otherwise, the legend chart will not be display (see below).

$legend

my $legend = "New data set";
$GraphDummies->add_data(\@NewData, $legend);

clearchart

$GraphDummies->clearchart: This method allows you to clear the chart. The canvas will not be destroy. It's possible to redraw your last chart using the redraw method.

delete_balloon

$GraphDummies->delete_balloon: If you call this method, you disable help identification which has been enabled with set_balloon method.

boxplot_information

$GraphDummies->boxplot_information

Use this method if you want to get the informations about all boxplots (25th percentile (Q1), 75th percentile (Q3), smallest non-outlier, largest non-outlier, median and mean). This method returns an array reference. The informations are stored in a hash reference.

my $ArrayRefInformation = $GraphDummies->boxplot_information();

# Print information of boxplot @{$data[2][3]} (2th sample, 4th data )
print "Boxplot @{$data[2][3]} (2th sample, 4th data )\n";
print "Outliers : @{$ArrayRefInformation->[1][3]->{outliers}}\n";
print "25th percentile (Q1) : ", $ArrayRefInformation->[1][3]->{Q1}, "\n";
print "75th percentile (Q3) :",  $ArrayRefInformation->[1][3]->{Q3}, "\n";
print "Smallest non-outlier : ",
  $ArrayRefInformation->[1][3]->{smallest_non_outlier}, "\n";
print "Largest non-outlier :", $ArrayRefInformation->[1][3]->{largest_non_outlier},
  "\n";
print "Median : ", $ArrayRefInformation->[1][3]->{median}, "\n";
print "Mean : ",   $ArrayRefInformation->[1][3]->{mean},   "\n";

if you have this data :

my @data = (
    [ "1st", "2nd", "3rd",  "4th", "5th" ],
    [ [ list data00 ],  [list data01],  [list data02], ],
    [ [ list data10 ],  [list data11],  [list data12], ],
    [ [ list data20 ],  [list data21],  [list data22], ],
    #...
  );

To get the informations about boxplot list data21, you have to read hash reference like this :

$Ref_hash_information = $ArrayRefInformation->[2][1];
# 25th percentile (Q1)
print $Ref_hash_information->{Q1};
# Smallest non-outlier
print $Ref_hash_information->{smallest_non_outlier};

The quantile is calculated with the same algorithm as Excel and type 7 quantile R package.

plot

$GraphDummies->plot(\@data, ?arg): To display your chart the first time, plot the chart by using this method.

\@data

Fill an array of arrays with the x values and the values of the datasets (\@data). Make sure that every array have the same size, otherwise Tk::ForDummies::Graph::Boxplots will complain and refuse to compile the graph.
```
my @data = (
  [ "1st", "2nd", "3rd",  "4th", "5th" ],
  [ [100 .. 125, 136 .. 140 ],  [22..89],  [12,54,88,10], [12,11,23,14..98,45], [0..55,11,12] ],
  [ [-25..-5, 1..15], [-45, 25..45, 100], [70, 42..125], [100, 30, 88, 95, 115, 155], [180..250] ],
  #...
);
```
@data have to contain a least two arrays, the x values and the values of the datasets. Each boxplot (array eg: [22..89]) have to contain at least 4 data.
```
[22,1,14] => wrong
```
If you don't have a value for a point in a dataset, you can use undef, and the point will be skipped.
```
[ undef,  [22..89],  [12,54,88,10], undef, [0..55,11,12] ],
```

-substitutionvalue => real number,

If you have a no real number value in a dataset, it will be replaced by a constant value.

Default : 0

my @data = (
     [     '1st',   '2nd', '3rd', '4th', '5th', '6th', '7th', '8th', '9th' ],
     [         1,    "--",     5,     6,     3,   1.5,     1,     3,     4 ],
     [ "mistake",       2,     5,     2,     3,  "NA",     7,     9,     4 ],
     [         1,       2,    52,     6,     3,  17.5,     1,    43,     4 ],
);
$GraphDummies->plot( \@data,
  -substitutionvalue => '12',
);
 # mistake, -- and NA will be replace by 12

-substitutionvalue have to be a real number (Eg : 12, .25, 02.25, 5.2e+11, ...)

redraw

Redraw the chart.

If you have used clearchart for any reason, it is possible to redraw the chart. Tk::ForDummies::Graph::Boxplots supports the configure and cget methods described in the Tk::options manpage. If you use configure method to change a widget specific option, the modification will not be display. If the chart was already displayed and if you not resize the widget, call redraw method to resolv the bug.

...
$fenetre->Button(-text => "Change xlabel", -command => sub { 
  $GraphDummies->configure(-xlabel => "red"); 
  } 
)->pack;
...
# xlabel will be changed but not displayed if you not resize the widget.
 
...
$fenetre->Button(-text => "Change xlabel", -command => sub { 
  $GraphDummies->configure(-xlabel => "red"); 
  $GraphDummies->redraw; 
  } 
)->pack;
...
# OK, xlabel will be changed and displayed without resize the widget.

set_balloon

$GraphDummies->set_balloon(? %Options): If you call this method, you enable help identification. When the mouse cursor passes over a plotted line or its entry in the legend, the line and its entry will be turn into a color (that you can change) to help the identification. set_legend method must be set if you want to enabled identification.

-background => string

Set a background color for the balloon.
```
-background => "red",
```
Default : snow
-colordatamouse => Array reference

Specify an array reference wich contains 2 colors. The first color specifies the color of the line when mouse cursor passes over a entry in the legend. If the line has the same color, the second color will be used.
```
-colordatamouse => ["blue", "green"],
```
Default : -colordatamouse => [ '#7F9010', '#CB89D3' ]
-morepixelselected => integer

When the mouse cursor passes over an entry in the legend, the line width increase.
```
-morepixelselected => 5,
```
Default : 1

set_legend

$GraphDummies->set_legend(? %Options): View a legend for the chart and allow to enabled identification help by using set_balloon method.

-title => string

Set a title legend.
```
-title => "My title",
```
Default : undef
-titlecolors => string

Set a color to legend text.
```
-titlecolors => "red",
```
Default : black
-titlefont => string

Set the font to legend title text.
```
-titlefont => "{Arial} 8 {normal}",
```
Default : {Times} 8 {bold}
-legendfont => string

Set the font to legend text.
```
-legendfont => "{Arial} 8 {normal}",
```
Default : {Times} 8 {normal}
-box => boolean

Set a box around all legend.
```
-box => 0,
```
Default : 1
-legendmarkerheight => integer

Change the heigth of marker for each legend entry.
```
-legendmarkerheight => 5,
```
Default : 10
-legendmarkerwidth => integer

Change the width of marker for each legend entry.
```
-legendmarkerwidth => 5,
```
Default : 10
-heighttitle => integer

Change the height title legend space.
```
-heighttitle => 75,
```
Default : 30

zoom

zoom the chart. The x axis and y axis will be zoomed. If your graph has a 300*300 size, after a zoom(200), the chart will have a 600*600 size.

$GraphDummies->zoom($zoom);

$zoom must be an integer great than 0.

$GraphDummies->zoom(50); # size divide by 2 => 150*150
...
$GraphDummies->zoom(200); # size multiplie by 2 => 600*600
...
$GraphDummies->zoom(120); # 20% add in each axis => 360*360
...
$GraphDummies->zoom(100); # original resize 300*300.

zoomx

zoom the chart the x axis.

# original canvas size 300*300
$GraphDummies->zoomx(50); # new size : 150*300
...
$GraphDummies->zoom(100); # new size : 300*300

zoomy

zoom the chart the y axis.

# original canvas size 300*300
$GraphDummies->zoomy(50); # new size : 300*150
...
$GraphDummies->zoom(100); # new size : 300*300

AUTHOR

Djibril Ousmanou, <djibel at cpan.org>

BUGS

Please report any bugs or feature requests to bug-Tk-ForDummies-Graph at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tk-ForDummies-Graph. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Tk::ForDummies::Graph::Boxplots

You can also look for information at:

RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tk-ForDummies-Graph
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Tk-ForDummies-Graph
CPAN Ratings

http://cpanratings.perl.org/d/Tk-ForDummies-Graph
Search CPAN

http://search.cpan.org/dist/Tk-ForDummies-Graph/

COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

To install Tk::ForDummies::Graph, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::ForDummies::Graph

CPAN shell

perl -MCPAN -e shell
install Tk::ForDummies::Graph

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

WIDGET-SPECIFIC OPTIONS like Tk::ForDummies::Graph::Lines

WIDGET METHODS

add_data

clearchart

delete_balloon

boxplot_information

plot

redraw

set_balloon

set_legend

zoom

zoomx

zoomy

AUTHOR

BUGS

SEE ALSO

SUPPORT

COPYRIGHT & LICENSE

NAME

SYNOPSIS

DESCRIPTION

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

WIDGET-SPECIFIC OPTIONS like Tk::ForDummies::Graph::Lines

WIDGET METHODS

add_data

clearchart

delete_balloon

boxplot_information

plot

redraw

set_balloon

set_legend

zoom

zoomx

zoomy

AUTHOR

BUGS

SEE ALSO

SUPPORT

COPYRIGHT & LICENSE

Module Install Instructions