/ 
Bio-Phylo-0.14
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Matrices::Matrix

NAME

Bio::Phylo::Matrices::Matrix - Character state matrix, implements Bio::CDAT::CharMatrixI

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
my $matrix = Bio::Phylo::Matrices::Matrix->new(
    '-taxa'   => $taxa,
    '-type'   => 'STANDARD',
    '-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' ],
    ],
);

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()
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   => required, 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_taxa()
Type    : Mutator
Title   : set_taxa
Usage   : $matrix->set_taxa( $taxa );
Function: Links the invocant matrix object
          to a taxa object. Individual datum
          objects are linked to individual taxon
          objects by name, i.e. by what is
          returned by $datum->get_name
Returns : $matrix
Args    : A Bio::Phylo::Taxa object.
Comments: This method checks whether any
          of the datum objects in the
          invocant link to Bio::Phylo::Taxa::Taxon
          objects not contained by $matrix. If
          found, these are set to undef and the
          following message is displayed:

          "Reset X references from datum objects
          to taxa outside taxa block"
set_charlabels()
Type    : Mutator
Title   : set_charlabels
Usage   : $matrix->set_charlabels( [ 'char1', 'char2', 'char3' ] );
Function: Assigns character labels.
Returns : $self
Args    : ARRAY

ACCESSORS

get_type()
Type    : Accessor
Title   : get_type
Usage   : my $type = $matrix->get_type;
Function: Retrieves a matrix's type.
Returns : SCALAR =~ (DNA|RNA|STANDARD|
          PROTEIN|NUCLEOTIDE|CONTINUOUS);
Args    : NONE
get_symbols()
Type    : Accessor
Title   : get_symbols
Usage   : my $symbols = $matrix->get_symbols;
Function: Retrieves a matrix's symbol table.
Returns : ARRAY
Args    : NONE
get_num_states()
Type    : Accessor
Title   : get_num_states
Usage   : my $nstates = $matrix->get_num_states;
Function: Retrieves the number of distinct
          states in the matrix
Returns : SCALAR
Args    : NONE
get_taxa()
Type    : Accessor
Title   : get_taxa
Usage   : my $taxa = $matrix->get_taxa;
Function: Retrieves the Bio::Phylo::Taxa
          object linked to the invocant.
Returns : Bio::Phylo::Taxa
Args    : NONE
Comments: This method returns the Bio::Phylo::Taxa
          object to which the invocant is linked.
          The returned object can therefore contain
          *more* taxa than are actually in the matrix.
get_chars_for_taxon()
Type    : Accessor
Title   : get_chars_for_taxon
Usage   : my @chars = @{
              $matrix->get_chars_for_taxon($taxon)
          };
Function: Retrieves the datum
          objects for $taxon
Returns : ARRAY
Args    : A Bio::Phylo::Taxa::Taxon object
get_cols()
Type    : Accessor
Title   : get_cols
Usage   : my $cols = $matrix->get_cols( 0 .. 100 );
Function: Retrieves columns in $matrix
Returns : Bio::Phylo::Matrices::Matrix (shallow copy)
Args    : Column numbers, zero-based,
          throws exception if out of bounds.
Notes   : This method can be used as a makeshift
          bootstrapper/jackknifer. The trick is to
          create the appropriate argument list, i.e.
          for bootstrapping one with the same number
          of elements as there are columns in the
          matrix - but resampled with replacement;
          for jackknifing a list where the number
          of elements is that of the number of columns
          to keep. You can generate such a list by
          iteratively calling shift(shuffle(@list))
          where shuffle comes from the List::Util
          package.
get_rows()
Type    : Accessor
Title   : get_rows
Usage   : my $rows = $matrix->get_rows( 0 .. 100 );
Function: Retrieves rows in $matrix
Returns : Bio::Phylo::Matrices::Matrix (shallow copy)
Args    : Row numbers, zero-based, throws
          exception if out of bounds.
Notes   :
get_charlabels()
Type    : Accessor
Title   : get_charlabels
Usage   : $matrix->get_charlabels;
Function: Retrieves character labels.
Returns : ARRAY
Args    : None.
get_missing()
Type    : Accessor
Title   : get_missing
Usage   : $matrix->get_missing;
Function: Retrieves the missing data symbol.
Returns : A single character.
Args    : None.
get_gap()
Type    : Accessor
Title   : get_gap
Usage   : $matrix->get_gap;
Function: Retrieves the gap (indel?) character symbol.
Returns : A single character.
Args    : None.
get_ntax()
Type    : Accessor
Title   : get_ntax
Usage   : my $ntax = $matrix->get_ntax;
Function: Retrieves the intended number of
          taxa for the matrix.
Returns : An integer, or undefined.
Args    : None.
Comments: The return value is whatever was
          set by the 'set_ntax' method call.
          'get_ntax' is used by the 'validate'
          method to check if the computed
          number of taxa matches with
          what is asserted here. In other words,
          this method does not return the
          *actual* number of taxa in the matrix
          (use 'get_num_taxa' for that), but the
          number it is supposed to have.
get_nchar()
Type    : Accessor
Title   : get_nchar
Usage   : $matrix->get_nchar;
Function: Retrieves the intended number of
          characters for the matrix.
Returns : An integer, or undefined.
Args    : None.
Comments: The return value is whatever was
          set by the 'set_nchar' method call.
          'get_nchar' is used by the 'validate'
          method to check if the computed
          number of characters matches with
          what is asserted here.

UTILITY METHODS

copy_atts()
Type    : Method
Title   : copy_atts
Usage   : my $copy = $matrix->copy_atts;
Function: Creates an empty copy of invocant
          (i.e. no data, but all the attributes).
Returns : Bio::Phylo::Matrices::Matrix (shallow copy)
Args    : None
to_nexus()
Type    : Format convertor
Title   : to_nexus
Usage   : my $data_block = $matrix->to_nexus;
Function: Converts matrix object into a nexus data block.
Alias   :
Returns : Nexus data block (SCALAR).
Args    : none
Comments:
to_cipres()
Type    : Format convertor
Title   : to_cipres
Usage   : my $cipres_matrix = $matrix->to_cipres;
Function: Converts matrix object to CipresIDL
Alias   :
Returns : CIPRES compliant data structure
Args    : none
Comments:
make_taxa()
Type    : Utility method
Title   : make_taxa
Usage   : my $taxa = $matrix->make_taxa;
Function: Creates a Bio::Phylo::Taxa object
          from the data in invocant.
Returns : Bio::Phylo::Taxa
Args    : NONE
Comments: NOTE: the newly created taxa
          object will replace all earlier
          references to other taxa and
          taxon objects.

DESTRUCTOR

DESTROY()
Type    : Destructor
Title   : DESTROY
Usage   : $phylo->DESTROY
Function: Destroys Phylo object
Alias   :
Returns : TRUE
Args    : none
Comments: You don't really need this,
          it is called automatically when
          the object goes out of scope.

Re-Implemented Bio::Matrix::MatrixI methods

Consult the Bio::Matrix::MatrixI documentation for details about the following methods:

matrix_id()
matrix_name()
num_rows()
num_columns()
row_names()
column_names()
column_num_for_name()

SEE ALSO

Bio::CDAT::CharMatrixI

This object implements the Bio::CDAT::CharMatrixI interface, so the methods defined therein are available here.

Bio::Phylo::Listable

This object inherits from Bio::Phylo::Listable, so the methods defined therein are also applicable to Bio::Phylo::Matrices::Matrix objects.

Bio::Phylo::Manual

Also see the manual: Bio::Phylo::Manual.

FORUM

CPAN hosts a discussion forum for Bio::Phylo. If you have trouble using this module the discussion forum is a good place to start posting questions (NOT bug reports, see below): http://www.cpanforum.com/dist/Bio-Phylo

BUGS

Please report any bugs or feature requests to bug-bio-phylo@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Phylo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. Be sure to include the following in your request or comment, so that I know what version you're using:

$Id: Matrix.pm 2187 2006-09-07 07:13:33Z rvosa $

AUTHOR

Rutger A. Vos,

email: rvosa@sfu.ca
web page: http://www.sfu.ca/~rvosa/

ACKNOWLEDGEMENTS

The author would like to thank Jason Stajich for many ideas borrowed from BioPerl http://www.bioperl.org, and CIPRES http://www.phylo.org and FAB* http://www.sfu.ca/~fabstar for comments and requests.

COPYRIGHT & LICENSE

Copyright 2005 Rutger A. Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.