| Bio::Phylo::Matrices::Matrix - Character state matrix |
Bio::Phylo::Matrices::Matrix - Character state matrix
use Bio::Phylo::Factory; my $fac = Bio::Phylo::Factory->new;
# instantiate taxa object my $taxa = $fac->create_taxa; for ( 'Homo sapiens', 'Pan paniscus', 'Pan troglodytes' ) { $taxa->insert( $fac->create_taxon( '-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 = $fac->create_matrix( '-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 the Bio::Phylo::Matrices::Datum manpage objects. The matrix object inherits from the Bio::Phylo::Listable manpage, so the methods defined there apply here.
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
new_from_bioperl()
Matrix constructor from Bio::Align::AlignI argument.
Type : Constructor Title : new_from_bioperl Usage : my $matrix = Bio::Phylo::Matrices::Matrix->new_from_bioperl( $aln ); Function: Instantiates a Bio::Phylo::Matrices::Matrix object. Returns : A Bio::Phylo::Matrices::Matrix object. Args : An alignment that implements Bio::Align::AlignI
Sets three special symbols in one call
Type : Mutator Title : set_special_symbols Usage : $matrix->set_special_symbols( -missing => '?', -gap => '-', -matchchar => '.' ); Function: Assigns state labels. Returns : $self Args : Three args (with distinct $x, $y and $z): -missing => $x, -gap => $y, -matchchar => $z Notes : This method is here to ensure you don't accidentally use the same symbol for missing AND gap
set_statelabels()
Sets argument state labels.
Type : Mutator Title : set_statelabels Usage : $matrix->set_statelabels( [ [ 'state1', 'state2' ] ] ); Function: Assigns state labels. Returns : $self Args : ARRAY, or nothing (to reset); The array is two-dimensional, the first index is to indicate the column the labels apply to, the second dimension the states (sorted numerically or alphabetically, depending on what's appropriate)
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
get_special_symbols()
Retrieves hash ref for missing, gap and matchchar symbols
Type : Accessor Title : get_special_symbols Usage : my %syms = %{ $matrix->get_special_symbols }; Function: Retrieves special symbols Returns : HASH ref, e.g. { -missing => '?', -gap => '-', -matchchar => '.' } Args : None.
get_statelabels()
Retrieves state labels.
Type : Accessor Title : get_statelabels Usage : my @statelabels = @{ $matrix->get_statelabels }; Function: Retrieves state labels. Returns : ARRAY Args : None.
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
bootstrap()
Creates bootstrapped clone.
Type : Utility method Title : bootstrap Usage : my $bootstrap = $object->bootstrap; Function: Creates bootstrapped clone. Returns : A bootstrapped clone of the invocant. Args : NONE Comments: The bootstrapping algorithm uses perl's random number generator to create a new series of indices (without replacement) of the same length as the original matrix. These indices are first sorted, then applied to the cloned sequences. Annotations (if present) stay connected to the resampled cells.
clone()
Clones invocant.
Type : Utility method Title : clone Usage : my $clone = $object->clone; Function: Creates a copy of the invocant object. Returns : A copy of the invocant. Args : NONE
to_xml()
Serializes matrix to nexml format.
Type : Format convertor Title : to_xml Usage : my $data_block = $matrix->to_xml; Function: Converts matrix object into a nexml element structure. Returns : Nexml block (SCALAR). Args : Optional: -compact => 1 (for compact representation of matrix)
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 or MISSING)" token -gapmode => 1 # if set, writes "MSTAXA=(POLYMORPH or UNCERTAIN)" token -polymorphism => 1 # if set, writes character labels -charlabels => 1 # if set, writes state labels -statelabels => 1 # if set, writes mesquite-style charstatelabels -charstatelabels => 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) -seqnames => one of (internal|taxon|taxon_internal|$key)
Analog to to_xml.
Type : Serializer
Title : to_dom
Usage : $matrix->to_dom
Function: Generates a DOM subtree from the invocant
and its contained objects
Returns : an Element object
Args : Optional:
-compact => 1 : renders characters as sequences,
not individual cells
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
compress_lookup()
Removes unused states from lookup table
Type : Method Title : validate Usage : $obj->compress_lookup Function: Removes unused states from lookup table Returns : $self Args : None
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
make_taxa()
Creates a taxa block from the objects contents if none exists yet.
Type : Method Title : make_taxa Usage : my $taxa = $obj->make_taxa Function: Creates a taxa block from the objects contents if none exists yet. Returns : $taxa Args : NONE
This object inherits from the Bio::Phylo::Taxa::TaxaLinker manpage, so the methods defined therein are also applicable to the Bio::Phylo::Matrices::Matrix manpage objects.
This object inherits from the Bio::Phylo::Matrices::TypeSafeData manpage, so the methods defined therein are also applicable to the Bio::Phylo::Matrices::Matrix manpage objects.
Also see the manual: the Bio::Phylo::Manual manpage and http://rutgervos.blogspot.com.
$Id: Matrix.pm 1175 2009-07-07 09:04:12Z rvos $
| Bio::Phylo::Matrices::Matrix - Character state matrix |