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"],
}
},
});
my $block = $rgraph->build_graph();
$rgraph->run_graph($block);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 <ab782@cornell.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_command 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();