NAME
R::YapRI::Graph::Simple.pm
A module to create simple graphs using R through R::YapRI::Base
SYNOPSIS
use R::YapRI::Base;
use R::YapRI::Data::Matrix;
use R::YapRI::Graph::Simple;
## Create rbase:
my $rbase = R::YapRI::Base->new();
## Create the data matrix
my $ymatrix = R::YapRI::Data::Matrix->new({
name => 'data1',
coln => 10,
rown => 2,
colnames => ['A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10'],
rownames => ['X', 'Y'],
data => [qw/ 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 /],
});
## Create the graph with the graph arguments, a barplot with two series (rows)
## of data per group (cols).
my $rgraph = R::YapRI::Graph::Simple->new({
rbase => $rbase,
rdata => { height => $ymatrix },
grfile => "MyFile.bmp",
device => { bmp => { width => 600, height => 600 } },
sgraph => { barplot => { beside => 'TRUE',
main => 'MyTitle',
xlab => 'x_axis_label',
ylab => 'y_axis_label',
col => ["dark red", "dark blue"],
}
},
});
$rgraph->build_graph('GRAPHBLOCK1');
my ($graphfile, $resultfile) = $rgraph->run_graph()DESCRIPTION
This module is a wrapper of R::YapRI::Base to create simple graphs using R, with the following features:
1) It loads the data from Perl to R using R::YapRI::Data::Matrix.
2) It works with blocks, so it can define a block in the beginning of the module/script and use as base to add the data and the graph creation commands.
3) It runs the following R commands acording the different accessors:
- device: bmp, jpeg, tiff, png, postscript or pdf.
- grparam: par.
- sgraph (high-level plotting commands): plot, pairs, hist, dotchart, barplot, pie or boxplot.
- gritems (low-level plotting commands): points, lines, abline, polygon, legend, title and axis.
4) It uses two commands to create the file with the graph:
+ build_graph(), to write into the R::YapRI::Base block the R commands.
+ run_graph(), to executate the R commands from the block.
AUTHOR
Aureliano Bombarely <aurebg@vt.edu>
CLASS METHODS
The following class methods are implemented:
(*) CONSTRUCTORS:
constructor new
Usage: my $rgraph = R::YapRI::Graph->new($arguments_href);
Desc: Create a new R graph object
Ret: a R::YapRI::Graph object
Args: A hash reference with the following parameters:
rbase => A R::YapRI::Base object
rdata => A hash reference with key=R_obj_name,
value=R::YapRI::Data::Matrix object
grfile => A filename
device => A hash reference with: key='grDevice name'
value=HASHREF. with grDevice args.
grparam => a hash reference with: key='par'
value=HASHREF. with par values.
sgraph => A hash reference with: key='high-level plotting function'
value=HASHREF. with plotting args
gritems => An array ref. of hash references with:
key='R low-level plotting command'
val='hash ref. with args. for that command'
Side_Effects: Die if the argument used is not a hash or its values arent
right.
Example: ## Default method:
my $rih = R::YapRI::Graph->new();
(*) ACCESSORS:
get/set_rbase
Usage: my $rbase = $rgraph->get_rbase();
$rgraph->set_rbase($rbase);
Desc: Get or set the rbase (R::YapRI::Base object) accessor
Ret: Get: $rbase, a R::YapRI::Base object
Set: none
Args: Get: none
Set: $rbase, a R::YapRI::Base object
Side_Effects: Get: None
Set: Die if no rbase object is supplied or if it isnt a
R::YapRI::Base object
Example: my $rbase = $rgraph->get_rbase();
$rgraph->set_rbase($rbase);
get/set_grfile
Usage: my $grfile = $rgraph->get_grfile();
$rgraph->set_grfile($grfile);
Desc: Get or set the grfile accessor.
It always will overwrite the filename argument for grDevice.
Ret: Get: $grfile, a scalar, a filename
Set: none
Args: Get: none
Set: $grfile, a scalar, filename
Side_Effects: Get: None
Set: Die if no grfile is supplied
Overwrite filename for grDevice
Example: my $grfile = $rgraph->get_grfile();
$rgraph->set_grfile('myfile.bmp');
get/set_rdata
Usage: my $rdata_href = $rgraph->get_rdata();
$rgraph->set_rdata($rdata_href);
Desc: Get or set the rdata accessor
Ret: Get: $rdata_href, a hash ref. with key = R.obj.name,
value = R::YapRI::Data::Matrix
Set: none
Args: Get: none
Set: $rdata_href, a hash ref. with key = R.obj.name,
value = R::YapRI::Data::Matrix
Side_Effects: Get: None
Set: Die if arg. supplied is not a hash reference or it dont
have R::YapRI::Data::Matrix objects.
Example: my %rdata = %{$rgraph->get_rdata()};
$rgraph->set_rdata({ ra => R::YapRI::Data::Matrix->new() });
get/set_device
Usage: my $device_href = $rgraph->get_device();
$rgraph->set_device($device_href);
Desc: Get or set the device accessor.
Permited grDevices: bmp, tiff, jpeg, png, pdf, postscript
Ret: Get: $device_href, a hash ref. with key=R.grDevice (bmp, tiff...)
val=HASHREF with arguments
Set: none
Args: Get: none
Set: $device_href, a hash ref. with key=R.grDevice (bmp, tiff...)
val=HASHREF with arguments
Side_Effects: Get: None
Set: Die if no hash ref. is supplied.
Die if grDevice isnt a permited device.
Die if the hashref. arguments isnt a hashref.
filename argument always will be overwrite for grfile
accessor.
Example: my $device_href = $rgraph->get_device();
$rgraph->set_device({ tiff => {} });
get/set_grparams
Usage: my $grparams_href = $rgraph->get_grparams();
$rgraph->set_grparams($grparams_href);
Desc: Get or set the graphical parameter accessor.
Use help(par) at the R terminal for more info.
Ret: Get: $grparam_href, a hash reference (see below)
Set: none
Args: Get: none
Set: $grparam_href, a hash reference.
Side_Effects: Get: None
Set: Die if no graphical parameter argument is supplied.
(empty hashref. is permited)
Die if it isnt a hash reference
Die if it doesnt use a permited parameter
Example: my %grparams = %{$rgraph->get_grparam()};
$rgraph->set_grparams({ par => { cex => 0.5 } });
get/set_sgraph
Usage: my $sgraph_href = $rgraph->get_sgraph();
$rgraph->set_sgraph($sgraph_href);
Desc: Get or set the simple graph accessor.
Permited high-level plot commands are: plot, pairs, hist, dotchart,
barplot, pie and boxplot.
Ret: Get: $sgraph_href, a hashref. with key=high-level plot command.
val=HASHREF. with plot arguments.
Set: none
Args: Get: none
Set: $sgraph_href, a hashref. with key=high-level plot command.
val=HASHREF. with plot arguments.
Side_Effects: Get: None
Set: Die if no sgraph is supplied or if it isnt the permited
list.
Die if argument hashref. isnt a hashref.
Example: my $sgraph = $rgraph->get_sgraph();
$rgraph->set_sgraph({ barplot => { beside => 'TRUE' } } );
get/set_gritems
Usage: my $gritems_href = $rgraph->get_gritems();
$rgraph->set_gritems($gritems_href);
Desc: Get or set the graph items arguments (low-level plotting commands)
accessor.
Use help() with a concrete gritem at the R terminal for more info.
Ret: Get: $gritems, an array reference of hash references with
key=R low-level plotting function
val=args. for that low-level func.
Set: none
Args: Get: none
Set: $gritems, an array reference of hash references with:
key=R low-level plotting function
val=args. for that low-level func.
Side_Effects: Get: None
Set: Die if no gritem argument is supplied (empty hash ref.
can be supplied)
Die if it isnt a array reference.
Die if rbase arg. was set before.
Die if the argument used it is not in the argument
permited list.
Die if the arguments used for the low-level plotting
function are not in the permited arguments, get using
R::YapRI::Base::r_function_args function + additional func.
for specific cases (example: col.main or cex.sub for title)
Example: my %gritems = %{$rgraph->get_gritems()};
$rgraph->set_gritems([
{ points => { x => [2, 5], col => "red" },
{ legend => { x => 25,
y => 50,
leg => ["exp1", "exp2", "exp3"],
bg => "gray90" }
]);
is_device_enabled
Usage: my $enabled = $rgraph->is_device_enabled($device_name, $block)
Desc: Check if the graphic device is enabled for the current block
Ret: 1 for enabled, 0 for disabled
Args: $device_name, a R graphical device name
$block, a block name to check, for a concrete rbase object
Side_Effects: Die if no deice_name or block are supplied.
Die if the block supplied doesnt exists in the rbase object
Example: if ($rgraph->is_device_enabled('bmp', 'BMPE')) {
print "R Device is enabled\n";
}
_rbase_check
Usage: $rgraph->_rbase_check();
Desc: Check if Rbase was set. Die if isnt set.
Ret: $rbase, Rbase object.
Args: None
Side_Effects: None
Example: $rgraph->_rbase_check();
_block_check
Usage: my $block = $rgraph->_block_check($block);
Desc: Check if a block exists into rbase object.
Create a new block if doesnt exists with that name.
Create a new block with name 'GRAPH_BUILD_XXXX if block isnt defined
Ret: $block, a block name.
Args: None
Side_Effects: None
Example: my $block = $rgraph->_block_check($block);
_sgraph_check
Usage: my $sgraph = $rgraph->_sgraph_check();
Desc: Check if a sgraph exists (accessor isnt empty) into rgraph object.
Die if is empty.
Ret: $sgraph, sgraph name for high-level plotting function
Args: None
Side_Effects: If there are more than one sgraph, order them and return
the first one.
Example: my $sgraph = $rgraph->_sgraph_check();
_rdata_check
Usage: my $robj = $rgraph->_rdata_check($primary_data_R);
Desc: Check if rdata exists (accessor isnt empty) into rgraph object.
Die if is empty.
Ret: $robj, a R object name for primary data (data used by the graph)
Args: $primary_data_R, according the simple graph used, the name of the
default primary data (for example: 'x' for plot or 'height' for barplot)
$mincol, min. number of columns for this method.
$maxcol, max. number of columns for this method.
Side_Effects: If there are more than one rdata, it will try to match the
R object name with the primary graph data
Example: my $robj = $rgraph->_rdata_check('height', 1, undef);
_rdata_loader
Usage: $rgraph->_rdata_loader($block);
Desc: Check and load the rdata
Ret: None
Args: $block, a block name for rbase
Side_Effects: Die if no block is used.
Die if block doesnt exist in the current rbase
Add the input R data object to sgraph hashref. If the sgraph
args. are a hash ref. it will convert them in a array ref. to
keep the order, and it will delete the arg. that refer to the
input data.
Example: $rgraph->_rdata_loader($block);
build_graph
Usage: my $block = $rgraph->build_graph($block);
Desc: A function to build the graph and return the block name.
Ret: $block, the name of the block where all the commands have been printed
Args: $block, a base block to add all the commands to create the graph
Side_Effects: Die if some of the accessors are empty
Example: my $block = $rgraph->build_graph();
$rgraph->build_graph("GRAPHBLOCK1");
run_graph
Usage: my ($filegraph, $fileresults) = $rgraph->run_graph();
Desc: A wrapper function to use run_commands over a concrete graph block
Ret: $filegraph, the name of the graph file
$fileresults, with the result of run all the R commans of this block
Args: None
Side_Effects: Die if some of the accessors are empty.
Return the filename for the graph from the grfile accessor
Example: my ($filegraph, $fileresults) = $rgraph->build_graph();
ACKNOWLEDGEMENTS
Lukas Mueller
Robert Buels
Naama Menda
Jonathan "Duke" Leto
COPYRIGHT AND LICENCE
Copyright 2011 Boyce Thompson Institute for Plant Research
Copyright 2011 Sol Genomics Network (solgenomics.net)
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.