NAME
Bio::Phylo::Matrices::Matrix - Character state matrix.
SYNOPSIS
use Bio::Phylo::Matrices::Matrix;
use Bio::Phylo::Taxa;
use Bio::Phylo::Taxa::Taxon;
# instantiate taxa object
my $taxa = Bio::Phylo::Taxa->new();
for ( 'Homo sapiens', 'Pan paniscus', 'Pan troglodytes' ) {
$taxa->insert( Bio::Phylo::Taxa::Taxon->new( '-name' => $_ ) );
}
# instantiate matrix object, 'standard' data type. All categorical
# data types follow semantics like this, though with different
# symbols in lookup table and matrix
my $standard_matrix = Bio::Phylo::Matrices::Matrix->new(
'-type' => 'STANDARD',
'-taxa' => $taxa,
'-lookup' => {
'-' => [],
'0' => [ '0' ],
'1' => [ '1' ],
'?' => [ '0', '1' ],
},
'-labels' => [ 'Opposable big toes', 'Opposable thumbs', 'Not a pygmy' ],
'-matrix' => [
[ 'Homo sapiens' => '0', '1', '1' ],
[ 'Pan paniscus' => '1', '1', '0' ],
[ 'Pan troglodytes' => '1', '1', '1' ],
],
);
# note: complicated constructor for mixed data!
my $mixed_matrix = Bio::Phylo::Matrices::Matrix->new(
# if you want to create 'mixed', value for '-type' is array ref...
'-type' => [
# ...with first field 'mixed'...
'mixed',
# ...second field is an array ref...
[
# ...with _ordered_ key/value pairs...
'dna' => 10, # value is length of type range
'standard' => 10, # value is length of type range
# ... or, more complicated, value is a hash ref...
'rna' => {
'-length' => 10, # value is length of type range
# ...value for '-args' is an array ref with args
# as can be passed to 'unmixed' datatype constructors,
# for example, here we modify the lookup table for
# rna to allow both 'U' (default) and 'T'
'-args' => [
'-lookup' => {
'A' => [ 'A' ],
'C' => [ 'C' ],
'G' => [ 'G' ],
'U' => [ 'U' ],
'T' => [ 'T' ],
'M' => [ 'A', 'C' ],
'R' => [ 'A', 'G' ],
'S' => [ 'C', 'G' ],
'W' => [ 'A', 'U', 'T' ],
'Y' => [ 'C', 'U', 'T' ],
'K' => [ 'G', 'U', 'T' ],
'V' => [ 'A', 'C', 'G' ],
'H' => [ 'A', 'C', 'U', 'T' ],
'D' => [ 'A', 'G', 'U', 'T' ],
'B' => [ 'C', 'G', 'U', 'T' ],
'X' => [ 'G', 'A', 'U', 'T', 'C' ],
'N' => [ 'G', 'A', 'U', 'T', 'C' ],
},
],
},
],
],
);
# prints 'mixed(Dna:1-10, Standard:11-20, Rna:21-30)'
print $mixed_matrix->get_type;DESCRIPTION
This module defines a container object that holds Bio::Phylo::Matrices::Datum objects. The matrix object inherits from Bio::Phylo::Listable, so the methods defined there apply here.
METHODS
CONSTRUCTOR
- new()
-
Matrix constructor.
Type : Constructor Title : new Usage : my $matrix = Bio::Phylo::Matrices::Matrix->new; Function: Instantiates a Bio::Phylo::Matrices::Matrix object. Returns : A Bio::Phylo::Matrices::Matrix object. Args : -type => optional, but if used must be FIRST argument, defines datatype, one of dna|rna|protein| continuous|standard|restriction|[ mixed => [] ] -taxa => optional, link to taxa object -lookup => character state lookup hash ref -labels => array ref of character labels -matrix => two-dimensional array, first element of every row is label, subsequent are characters
MUTATORS
- set_charlabels()
-
Sets argument character labels.
Type : Mutator Title : set_charlabels Usage : $matrix->set_charlabels( [ 'char1', 'char2', 'char3' ] ); Function: Assigns character labels. Returns : $self Args : ARRAY, or nothing (to reset); - set_gapmode()
-
Defines matrix gapmode.
Type : Mutator Title : set_gapmode Usage : $matrix->set_gapmode( 1 ); Function: Defines matrix gapmode ( false = missing, true = fifth state ) Returns : $self Args : boolean - set_matchchar()
-
Assigns match symbol.
Type : Mutator Title : set_matchchar Usage : $matrix->set_matchchar( $match ); Function: Assigns match symbol (default is '.'). Returns : $self Args : ARRAY - set_polymorphism()
-
Defines matrix 'polymorphism' interpretation.
Type : Mutator Title : set_polymorphism Usage : $matrix->set_polymorphism( 1 ); Function: Defines matrix 'polymorphism' interpretation ( false = uncertainty, true = polymorphism ) Returns : $self Args : boolean - set_raw()
-
Set contents using two-dimensional array argument.
Type : Mutator Title : set_raw Usage : $matrix->set_raw( [ [ 'taxon1' => 'acgt' ], [ 'taxon2' => 'acgt' ] ] ); Function: Syntax sugar to define $matrix data contents. Returns : $self Args : A two-dimensional array; first dimension contains matrix rows, second dimension contains taxon name / character string pair. - set_respectcase()
-
Defines matrix case sensitivity interpretation.
Type : Mutator Title : set_respectcase Usage : $matrix->set_respectcase( 1 ); Function: Defines matrix case sensitivity interpretation ( false = disregarded, true = "respectcase" ) Returns : $self Args : boolean
ACCESSORS
- get_charlabels()
-
Retrieves character labels.
Type : Accessor Title : get_charlabels Usage : my @charlabels = @{ $matrix->get_charlabels }; Function: Retrieves character labels. Returns : ARRAY Args : None. - get_gapmode()
-
Returns matrix gapmode.
Type : Accessor Title : get_gapmode Usage : do_something() if $matrix->get_gapmode; Function: Returns matrix gapmode ( false = missing, true = fifth state ) Returns : boolean Args : none - get_matchchar()
-
Returns matrix match character.
Type : Accessor Title : get_matchchar Usage : my $char = $matrix->get_matchchar; Function: Returns matrix match character (default is '.') Returns : SCALAR Args : none - get_nchar()
-
Calculates number of characters.
Type : Accessor Title : get_nchar Usage : my $nchar = $matrix->get_nchar; Function: Calculates number of characters (columns) in matrix (if the matrix is non-rectangular, returns the length of the longest row). Returns : INT Args : none - get_ntax()
-
Calculates number of taxa (rows) in matrix.
Type : Accessor Title : get_ntax Usage : my $ntax = $matrix->get_ntax; Function: Calculates number of taxa (rows) in matrix Returns : INT Args : none - get_polymorphism()
-
Returns matrix 'polymorphism' interpretation.
Type : Accessor Title : get_polymorphism Usage : do_something() if $matrix->get_polymorphism; Function: Returns matrix 'polymorphism' interpretation ( false = uncertainty, true = polymorphism ) Returns : boolean Args : none - get_raw()
-
Retrieves a 'raw' (two-dimensional array) representation of the matrix's contents.
Type : Accessor Title : get_raw Usage : my $rawmatrix = $matrix->get_raw; Function: Retrieves a 'raw' (two-dimensional array) representation of the matrix's contents. Returns : A two-dimensional array; first dimension contains matrix rows, second dimension contains taxon name and characters. Args : NONE - get_respectcase()
-
Returns matrix case sensitivity interpretation.
Type : Accessor Title : get_respectcase Usage : do_something() if $matrix->get_respectcase; Function: Returns matrix case sensitivity interpretation ( false = disregarded, true = "respectcase" ) Returns : boolean Args : none
METHODS
- to_nexus()
-
Serializes matrix to nexus format.
Type : Format convertor Title : to_nexus Usage : my $data_block = $matrix->to_nexus; Function: Converts matrix object into a nexus data block. Returns : Nexus data block (SCALAR). Args : The following options are available: # if set, writes TITLE & LINK tokens '-links' => 1 # if set, writes block as a "data" block (deprecated, but used by mrbayes), # otherwise writes "characters" block (default) -data_block => 1 # if set, writes "RESPECTCASE" token -respectcase => 1 # if set, writes "GAPMODE=(NEWSTATE of MISSING)" token -gapmode => 1 # if set, writes "MSTAXA=(POLYMORPH or UNCERTAIN)" token -polymorphism => 1 # if set, writes character labels -charlabels => 1 # by default, names for sequences are derived from $datum->get_name, if # 'internal' is specified, uses $datum->get_internal_name, if 'taxon' # uses $datum->get_taxon->get_name, if 'taxon_internal' uses # $datum->get_taxon->get_internal_name, if $key, uses $datum->get_generic($key) -tipnames => one of (internal|taxon|taxon_internal|$key) - insert()
-
Insert argument in invocant.
Type : Listable method Title : insert Usage : $matrix->insert($datum); Function: Inserts $datum in $matrix. Returns : Modified object Args : A datum object Comments: This method re-implements the method by the same name in Bio::Phylo::Listable - validate()
-
Validates the object's contents.
Type : Method Title : validate Usage : $obj->validate Function: Validates the object's contents Returns : True or throws Bio::Phylo::Util::Exceptions::InvalidData Args : None Comments: This method implements the interface method by the same name in Bio::Phylo::Matrices::TypeSafeData - check_taxa()
-
Validates taxa associations.
Type : Method Title : check_taxa Usage : $obj->check_taxa Function: Validates relation between matrix and taxa block Returns : Modified object Args : None Comments: This method implements the interface method by the same name in Bio::Phylo::Taxa::TaxaLinker
SEE ALSO
- Bio::Phylo::Taxa::TaxaLinker
-
This object inherits from Bio::Phylo::Taxa::TaxaLinker, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Matrix objects.
- Bio::Phylo::Matrices::TypeSafeData
-
This object inherits from Bio::Phylo::Matrices::TypeSafeData, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Matrix objects.
- Bio::Phylo::Manual
-
Also see the manual: Bio::Phylo::Manual.
REVISION
$Id: Matrix.pm 4265 2007-07-20 14:14:44Z rvosa $