Aureliano Bombarely > R-YapRI-0.08 > R::YapRI::Graph::Simple

Download:
R-YapRI-0.08.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.04   Source  

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 <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();

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.

syntax highlighting: