Bio::Phylo::Matrices::Matrix - Character state matrix.
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;
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.
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
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);
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
Assigns match symbol.
Type : Mutator Title : set_matchchar Usage : $matrix->set_matchchar( $match ); Function: Assigns match symbol (default is '.'). Returns : $self Args : ARRAY
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 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.
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
Retrieves character labels.
Type : Accessor
Title : get_charlabels
Usage : my @charlabels = @{ $matrix->get_charlabels };
Function: Retrieves character labels.
Returns : ARRAY
Args : None.
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
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
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
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
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
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
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
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 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
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
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
This object inherits from Bio::Phylo::Taxa::TaxaLinker, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Matrix objects.
This object inherits from Bio::Phylo::Matrices::TypeSafeData, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Matrix objects.
Also see the manual: Bio::Phylo::Manual.
$Id: Matrix.pm 4265 2007-07-20 14:14:44Z rvosa $
