Aureliano Bombarely

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.