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({ name => '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 <aurebg@vt.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.
If no coln and rown are used, it will set to 0 by default.
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.