Aureliano Bombarely > R-YapRI-0.08 > R::YapRI::Data::Matrix

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::Data::Matrix.pm

A module to build and pass a Matrix to a YapRI command file

SYNOPSIS ^

  use R::YapRI::Base;
  use R::YapRI::Data::Matrix;

  ## Constructors:

  my $rmatrix = R::YapRI::Data::Matrix->new('matrix1');
  
  ## Accessors:

  my $matrixname = $rmatrix->get_name();
  $rmatrix->set_name('matrix');

  my $coln = $rmatrix->get_coln();
  $rmatrix->set_coln(3);

  my $rown = $rmatrix->get_rown();
  $rmatrix->set_rown(4);

  my @data = $rmatrix->get_data();
  $rmatrix->set_data(\@data);

  my @colnames = $rmatrix->get_colnames();
  $rmatrix->set_colnames(\@colnames);

  my @rownames = $rmatrix->get_colanmes();
  $rmatrix->set_colnames(\@rownames);

  ## Adding/deleting/changing data:

  $rmatrix->set_coldata($colname, [$y1, $y2, $y3, $y4]);
  $rmatrix->set_rowdata($rowname, [$x1, $x2, $x3]);
  
  $rmatrix->add_column($colname, [$yy1, $yy2, $yy3, $yy4]);
  $rmatrix->add_row($rowname, [$xx1, $xx2, $xx3]);

  my @oldcol = $rmatrix->remove_column($colname);
  my @oldrow = $rmatrix->remove_row($rowname);

  $rmatrix->change_columns($col_x, $col_z);
  $rmatrix->change_rows($row_x, $row_z);


  ## Parsers:
     
  my $rbase = R::YapRI::Base->new();
  $rmatrix->send_rbase($rbase, $mode);
 
  $rmatrix = R::YapRI::Data::Matrix->read_rbase($rbase, $block, $r_object_name);

  ## Slicers:

  my @col2 = $rmatrix->get_column($col_y);
  my @row3 = $rmatrix->get_row($row_x);
  my $elem2_3 = $rmatrix->get_element($row_x, $col_y);

DESCRIPTION ^

R::YapRI::Data::Matrix is a R::YapRI to manipulate matrices, send to an rbase object (R::YapRI::Base) for further R manipulations.

This module pass perl variables to a R::YapRI::Data::Matrix object that convert them in a R command line that it is passed to R::YapRI::Base object as a block.

 +-----------+    +----------------------+    +------------+    +---+--------+
 | PerlData1 | => | YaRI::Data::Matrix 1 | => |            | => |   | Input  |
 +-----------+    +----------------------+    | YaRI::Base |    | R |--------+
 | PerlData2 | <= | YaRI::Data::Matrix 2 |<=  |            | <= |   | Output |
 +-----------+    +----------------------+    +------------+    +---+--------+

It lets export data to R frame as: matrix (default), data.frames, vector (by_rows or by_columns) and list (by_rows or by_columns).

Rbase communication is based in two functions:

+ send_rbase, to add the matrix to a rbase block.

+ read_rbase, to create a R::YapRI::Data::Matrix based in a R matrix contained in a rbase block.

AUTHOR ^

Aureliano Bombarely <ab782@cornell.edu>

CLASS METHODS ^

The following class methods are implemented:

(*) CONSTRUCTORS: ^

constructor new

  Usage: my $rmatrix = R::YapRI::Data::Matrix->new();

  Desc: Create a new R::YapRI::Data::Matrix object

  Ret: a R::YapRI::Data::Matrix object

  Args: A hash reference with the following parameters:
          name     => a scalar with the matrix name, 
          coln     => a scalar with the column number (int),
          rown     => a scalar with the row number (int),
          colnames => an array ref. with the column names,
          rownames => an array ref. with the row names,
          data     => an array ref. with the matrix data ordered by row.        
        
  Side_Effects: Die if the argument used is not a hash or its values arent 
                right.

  Example: my $rmatrix = R::YapRI::Data::Matrix->new(
                                     { 
                                       name     => 'matrix1',
                                       coln     => 3,
                                       rown     => 4,
                                       colnames => ['a', 'b', 'c'],
                                       rownames => ['W', 'X', 'Y', 'Z'],
                                       data     => [ 1, 1, 1, 2, 2, 2, 
                                                     3, 3, 3, 4, 4, 4,],
                                     }
                                   );

(*) ACCESSORS: ^

get_name

  Usage: my $name = $matrix->get_name();

  Desc: Get the Matrix name for a R::YapRI::Data::Matrix object

  Ret: $name, a scalar

  Args: None    
        
  Side_Effects: None

  Example: my $name = $matrix->get_name();

set_name

  Usage: $matrix->set_name($name);

  Desc: Set the Matrix name for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $name, an scalar    
        
  Side_Effects: Die if undef value is used 

  Example: $matrix->set_name($name);

get_coln

  Usage: my $coln = $matrix->get_coln();

  Desc: Get the matrix column number for a R::YapRI::Data::Matrix object

  Ret: $coln, a scalar

  Args: None    
        
  Side_Effects: None

  Example: my $coln = $matrix->get_coln();

set_coln

  Usage: $matrix->set_coln($coln);

  Desc: Set the matrix column number for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $coln, an scalar    
        
  Side_Effects: Die if undef value is used.
                Die if colnum number is not a digit

  Example: $matrix->set_coln($coln);

get_rown

  Usage: my $rown = $matrix->get_rown();

  Desc: Get the matrix row number for a R::YapRI::Data::Matrix object

  Ret: $rown, a scalar

  Args: None    
        
  Side_Effects: None

  Example: my $rown = $matrix->get_rown();

set_rown

  Usage: $matrix->set_rown($rown);

  Desc: Set the matrix row number for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $rown, an scalar    
        
  Side_Effects: Die if undef value is used.
                Die if rown number is not a digit

  Example: $matrix->set_rown($rown);

get_colnames

  Usage: my $colnames_aref = $matrix->get_colnames();

  Desc: Get the Matrix column names array for a R::YapRI::Data::Matrix object

  Ret: $colnames_aref, an array reference with the column names

  Args: None    
        
  Side_Effects: None

  Example: my @colnames = @{$matrix->get_colnames()};

set_colnames

  Usage: $matrix->set_colnames(\@colnames);

  Desc: Set the matrix column names array for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $col_names_aref, an array reference with the column names
        
  Side_Effects: Die if undef value is used
                Die if argument is not an array reference.
                Die if number of element in the array isnt equal to coln value.
                (except if colnumber is empty)

  Example: $matrix->set_colnames(['col1', 'col2']);

get_rownames

  Usage: my $rownames_aref = $matrix->get_rownames();

  Desc: Get the Matrix row names array for a R::YapRI::Data::Matrix object

  Ret: $rownames_aref, an array reference with the row names

  Args: None    
        
  Side_Effects: None

  Example: my @rownames = @{$matrix->get_rownames()};

set_rownames

  Usage: $matrix->set_rownames(\@rownames);

  Desc: Set the matrix row names array for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $row_names_aref, an array reference with the row names
        
  Side_Effects: Die if undef value is used
                Die if argument is not an array reference.
                Die if number of element in the array isnt equal to rown value.
                (except if rownumber is empty)

  Example: $matrix->set_rownames(['row1', 'row2']);

get_data

  Usage: my $data_aref = $matrix->get_data();

  Desc: Get the matrix data array for a R::YapRI::Data::Matrix object.
        The data is stored as an array ordered by rows.

        Example: Matrix  |1 2 3|  => [1, 2, 3, 4, 5, 6]
                         |4 5 6|
 
  Ret: $data_aref, an array reference with the data as array

  Args: None    
        
  Side_Effects: None

  Example: my @data = @{$matrix->get_data()};

set_data

  Usage: $matrix->set_data(\@data);

  Desc: Set the matrix data array for a R::YapRI::Data::Matrix object

  Ret: None

  Args: $data, an array reference with the data ordered by rows

         Example: Matrix  |1 2 3|  => [1, 2, 3, 4, 5, 6]
                          |4 5 6|
        
  Side_Effects: Die if undef value is used
                Die if argument is not an array reference.
                Die if number of element in the array isnt equal to  
                coln x rown (for example if coln=3 and rown=2, it should have
                6 elements)

  Example: $matrix->set_data([1, 2, 3, 4]);

(*) INTERNAL MATRIX FUNCTIONS: ^

_get_indexes

  Usage: my $index_href = $matrix->_get_indexes();

  Desc: Get then matrix indexes for columns and rows, with the following 
        format:
          $index_href = { $row,$col => $array_element }
 
  Ret: $index_href, a hash reference with the matrix indexes.

  Args: None    
        
  Side_Effects: None

  Example: my %indexes = @{$matrix->_get_indexes()};

_get_rev_indexes

  Usage: my $revindex_href = $matrix->_get_rev_indexes();

  Desc: Get then matrix indexes for columns and rows, with the following 
        format:
          $index_href = { $array_element => [ $row, $col ] }
 
  Ret: $rindex_href, a hash reference with the matrix indexes.

  Args: None    
        
  Side_Effects: None

  Example: my %revindexes = %{$matrix->_get_rev_indexes()};

_set_indexes

  Usage: $matrix->_set_indexes(\%indexes);

  Desc: Set the matrix indexes for the data contained in the matrix

  Ret: None

  Args: \%indexes, a hash reference with key=$row,$col and value=$arrayposition
        
  Side_Effects: Die if undef value is used
                Die if argument is not an hash reference.
                Die if number of element in the hash isnt equal to  
                coln x rown (for example if coln=3 and rown=2, it should have
                6 elements)

  Example: $matrix->set_data([1, 2, 3, 4]);

_index_matrix

  Usage: my %index_matrix = $self->_index_matrix();

  Desc: Index the matrix with an array to know segment the matrix in elements
        %index_matrix = ( $arrayposition => { row => $rowposition,
                                              col => $colposition 
                                            });
 
  Ret: The index matrix, a hash with the following elements:
       %index_matrix = ( $arrayposition => { $rowposition, $colposition })

  Args: None  
        
  Side_Effects: None

  Example: my %index_matrix = $self->_index_matrix();

_no_duplicate_names

  Usage: $rmatrix->_no_duplicate_names($method);

  Desc: Check if there are duplicate names for col or rows. Die if exists
        duplicates.
 
  Ret: None

  Args: $method, a scalar that can have 'col', 'row' or 'all'. (all by default)
        
  Side_Effects: Overwrite methods that are not 'col' or 'row' with 'all'. 
                Die if it find duplicates.

  Example: $rmatrix->_no_duplicate_names('col');

(*) DATA MANAGEMENT FUNCTIONS: ^

set_coldata

  Usage: $rmatrix->set_coldata($colname, \@col_data);

  Desc: Add data to an existing column, overwriting the old data
 
  Ret: None

  Args: $colname, a scalar with the name of the column
        $coldata_aref, an array ref. with the data of the column    
        
  Side_Effects: Die if no colname is used.
                Die if the number of elements in the data array is different
                than the rown

  Example: $rmatrix->set_coldata('col1', [1, 2]);
           $rmatrix->set_coldata($colnames[0], [1, 2]);

set_rowdata

  Usage: $rmatrix->set_rowdata($rowname, \@row_data);

  Desc: Add data to an existing row, overwriting the old data
 
  Ret: None

  Args: $colname, a scalar with the name of the row,
        $rowdata_aref, an array ref. with the data of the row   
        
  Side_Effects: Die if no rowname is used.
                Die if the number of elements in the data array is different
                than the column

  Example: $rmatrix->set_rowdata('row1', [1, 2]);
           $rmatrix->set_rowdata($rownames[0], [1, 2]);

add_column

  Usage: $rmatrix->add_column($colname, \@col_data);

  Desc: Add a new column to the object, rebuilding the indexes and edinting
        column number
 
  Ret: None

  Args: $colname, a scalar with the name of the column
        $coldata_aref, an array ref. with the data of the column    
        
  Side_Effects: Die if the number of elements in the data array is different
                than the row number
                Rebuild and reset the matrix indexes and the coln.

  Example: $rmatrix->add_column('col1', [1, 2]);

add_row

  Usage: $rmatrix->add_row($rowname, \@row_data);

  Desc: Add a new row to the object, rebuilding the indexes and edinting
        row number
 
  Ret: None

  Args: $rowname, a scalar with the name of the row
        $rowdata_aref, an array ref. with the data of the row   
        
  Side_Effects: Die if the number of elements in the data array is different
                than the col number
                Rebuild and reset the matrix indexes and the rown.

  Example: $rmatrix->add_row('row3', [1, 2]);

delete_column

  Usage: my @coldata = $rmatrix->delete_column($colname);

  Desc: Delete a column to the object, rebuilding the indexes and edinting
        column number
 
  Ret: @coldata, an array with the column data deleted

  Args: $colname, a scalar with the name of the column  
        
  Side_Effects: Die if the column doesnt exist.
                Rebuild indexes and reset coln.

  Example: my @coldata = $rmatrix->delete_column('col1');

delete_row

  Usage: my @rowdata = $rmatrix->delete_row($rowname);

  Desc: Delete a row to the object, rebuilding the indexes and edinting
        row number
 
  Ret: @rowdata, an array with the row data deleted

  Args: $rowname, a scalar with the name of the row  
        
  Side_Effects: Die if the row doesnt exist.
                Rebuild indexes and reset rown.

  Example: my @rowdata = $rmatrix->delete_row('row1');

change_columns

  Usage: $rmatrix->change_columns($colname1, $colname2);

  Desc: Change the order of two columns
 
  Ret: None

  Args: $colname1, column name 1, 
        $colname2, column name 2,  
        
  Side_Effects: Die if the any of the column names used doesnt exist.

  Example: $rmatrix->change_columns('col1', 'col2');

change_rows

  Usage: $rmatrix->change_rows($rowname1, $rowname2);

  Desc: Change the order of two rows
 
  Ret: None

  Args: $rowname1, row name 1, 
        $rowname2, row name 2,  
        
  Side_Effects: Die if the any of the row names used doesnt exist.

  Example: $rmatrix->change_rows('row1', 'row2');

transpose

  Usage: my $newmatrix = $rmatrix->matrix($matrixname);

  Desc: Create a new matrix executing a transpose over the original matrix
 
  Ret: $newmatrix, a R::YapRI::Data::Matrix object

  Args: $matrixname, a new matrix name
        
  Side_Effects: Use tr_ . $rmatrix->get_name as default name.

  Example: my $newmatrix = $rmatrix->matrix();

get_column

  Usage: my @column = $rmatrix->get_column($colname);

  Desc: Get the column data for a concrete columnname
 
  Ret: @column, an array with the column data

  Args: $colname, a scalar with the column name
        
  Side_Effects: return an empty array if the column doesnt exist

  Example: my @column2 = $rmatrix->get_column('column2');

get_row

  Usage: my @row = $rmatrix->get_row($rowname);

  Desc: Get the row data for a concrete rowname
 
  Ret: @row, an array with the row data

  Args: $rowname, a scalar with the row name
        
  Side_Effects: return an empty array if the row doesnt exist

  Example: my @row3 = $rmatrix->get_row('row3');

get_element

  Usage: my $element = $rmatrix->get_element($rowname, $colname);

  Desc: Get the matrix element for concrete $rowname, $colname pair
 
  Ret: $element, a scalar with the element value

  Args: $rowname, a scalar with the row name
        $colname, a scalar with the column name
        
  Side_Effects: return undef if the row or/and column doesnt exist

  Example: my $element = $rmatrix->get_element($rowname, $colname);

(*) R. FUNCTIONS: ^

_matrix_cmd

  Usage: my $cmd = $rmatrix->_matrix_cmd();

  Desc: Build the command to add a new matrix 
 
  Ret: $cmd, a string with the R command

  Args: None
        
  Side_Effects: None

  Example: my $cmd = $rmatrix->_matrix_cmd();

_dataframe_cmd

  Usage: my $cmd = $rmatrix->_dataframe_cmd();

  Desc: Build the command to add a new dataframe to R block
 
  Ret: $cmd, a string with the R command

  Args: None
        
  Side_Effects: If the column names are numeric (f.example: 1), it will
                add an X before (R doesnt accept numeric column names)

  Example: my $cmd = $rmatrix->_dataframe_cmd();

_rowvectors_cmd

  Usage: my $cmds_aref = $rmatrix->_rowvectors_cmd();

  Desc: Build the command to add a list of vectors, parsing the matrix
        by rows 
 
  Ret: $cmds_aref, an array ref. with strings with the R command

  Args: None
        
  Side_Effects: Create as many vectors as rows has the matrix, with the
                row names as vector names. If the row names are numeric, 
                it will add an 'X' before the number (for example, 67 will
                be X67).

  Example: my @cmds = @{$rmatrix->_rowvectors_cmd()};

_colvectors_cmd

  Usage: my $cmds_aref = $rmatrix->_colvectors_cmd();

  Desc: Build the command to add a list of vectors, parsing the matrix
        by columns 
 
  Ret: $cmds_aref, an array ref. strings with the R command

  Args: None
        
  Side_Effects: Create as many vectors as cols has the matrix, with the
                col names as vector names. If the col names are numeric, 
                it will add an 'X' before the number (for example, 67 will
                be X67).

  Example: my @cmds = @{$rmatrix->_colvectors_cmd()};

send_rbase

  Usage: $rmatrix->send_rbase($rbase, $block, $mode);

  Desc: Load the matrix data as a block in a rbase object (R::YapRI::Base)
        The R matrix name will the same than the perl matrix name.
        If block argument is used, it will add the command to this block.
        If block argument is undef or empty, it will create a new block with
        the argument name
 
  Ret: None

  Args: $rbase, a R::YapRI::Base object, 
        $block, block to create or add the data, an undef or empty value
                will create a new block with the matrix name.
        $mode, a scalar with the following possible values matrix, dataframe
               vectors_by_row and vectors_by_col (optional, matrix by default)
             
 
  Side_Effects: Die if no rbase object is used or if the argument used
                is not a R::YapRI::Base object

  Example: ## Default mode (R matrix in a new block with name=matrix_name)
              $rmatrix->send_rbase($rbase);

           ## Adding a matrix to BLOCK1
              $rmatrix->send_rbase($rbase, 'BLOCK1');

           ## Adding a data.frame to GRAPH1
              $rmatrix->send_rbase($rbase, 'GRAPH1', 'dataframe');

           ## Adding as vectors by row to a matrix name block 
              $rmatrix->send_rbase($rbase, '', 'vectors_by_row');

read_rbase

  Usage: my $rmatrix = R::YapRI::Data::Matrix->read_rbase( $rbase, 
                                                        $block, 
                                                        $r_object_name);

  Desc: Create a new block with some R functions to get the data from the
        matrix. Combine it with the base block, run it and get the resultsfile.
        Parse the resultfile and get the data from it, loading it in a new
        matrix object. 
 
  Ret: A new matrix object (R::YapRI::Data::Matrix)

  Args: $rbase, a R::YapRI::Base object, 
        $block, a scalar with the name of the block that contains the R object
                to be read
        $r_object_name, name of the r_object to read
        
  Side_Effects: Die if no rbase object, block name or r_object_name is used.
                Die if rbase objects isnt a R::YapRI::Base object
                Die if block doesnt exist in the R::YapRI::Base object
                Die if the r_object_name doesnt exist in the R block used
                Die if the r_object_name isnt a matrix object.

  Example:  my $rmatrix = R::YapRI::Data::Matrix->read_rbase( $rbase, 
                                                           'BLOCK1', 
                                                           'mymatrix');

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: