Bio::Phylo::Matrices::Matrix(3)

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' ],
     },
     '-charlabels' => [ '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>