NAME

Bio::Phylo::Matrices::Matrix - Character state matrix

SYNOPSIS

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;

DESCRIPTION

This module defines a container object that holds Bio::Phylo::Matrices::Datum objects. The matrix object inherits from Bio::Phylo::MatrixRole, so the methods defined there apply here.

METHODS

MUTATORS

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_characters()

Sets the character set manager object Bio::Phylo::Matrices::Characters. Normally you never have to use this.

Type    : Mutator
Title   : set_characters
Usage   : $matrix->set_characters( $characters );
Function: Assigns Bio::Phylo::Matrices::Characters object
Returns : $self
Args    : Bio::Phylo::Matrices::Characters

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_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_characters()

Retrieves characters object.

Type    : Accessor
Title   : get_characters
Usage   : my $characters = $matrix->get_characters
Function: Retrieves characters object.
Returns : Bio::Phylo::Matrices::Characters
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_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_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_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

SEE ALSO

There is a mailing list at https://groups.google.com/forum/#!forum/bio-phylo for any user or developer questions and discussions.

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 and http://rutgervos.blogspot.com.

CITATION

If you use Bio::Phylo in published research, please cite it:

Rutger A Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase Miller, 2011. Bio::Phylo - phyloinformatic analysis using Perl. BMC Bioinformatics 12:63. http://dx.doi.org/10.1186/1471-2105-12-63