NAME

Bio::Phylo::Matrices::Matrix - The matrix object to aggregate datum objects.

SYNOPSIS

use Bio::Phylo::Matrices::Matrix;
use Bio::Phylo::Matrices::Datum;
use Bio::Phylo::Taxa::Taxon;

# instantiate matrix object
my $matrix = Bio::Phylo::Matrices::Matrix->new;

# instantiate a taxon object
my $taxon = Bio::Phylo::Taxa::Taxon->new;

# instantiate 1000 datum objects and insert them in the matrix
for my $i ( 0 .. 1000 ) {
   my $datum = Bio::Phylo::Matrices::Datum->new( 
       -pos   => $i,
       -type  => 'STANDARD',
       -taxon => $taxon,
       -char  => int(rand(2)),
   );
   $matrix->insert($datum);
}

# retrieve all datum objects whose position >= 500
my @second_half_of_matrix = @{ $matrix->get_by_value(
   -value => 'get_position',
   -ge    => 500
) };

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    : NONE required, but look up the inheritance 
          tree to the SUPER class Bio::Phylo::Listable, 
          and its parent Bio::Phylo

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

Type    : Mutator
Title   : set_type
Usage   : $matrix->set_type($type);
Function: Assigns a matrix's type.
Returns : Modified object.
Args    : $type must be one of [DNA|RNA|STANDARD|
          PROTEIN|NUCLEOTIDE|CONTINUOUS]. If no 
          argument supplied, matrix type is set 
          to undefined.

set_symbols()

Type    : Mutator
Title   : set_symbol
Usage   : $matrix->set_symbols($symbols);
Function: Assigns/adds an array ref 
          of allowed symbols
Returns : Modified object.
Args    : A reference to an array of symbols. 
          When no argument is given,
          the symbol table is reset.

set_missing()

Type    : Mutator
Title   : set_missing
Usage   : $matrix->set_missing('?');
Function: Assigns the missing character symbol.
Returns : Modified object.
Args    : A symbol used to indicate missing
          data. Default is '?'.

set_gap()

Type    : Mutator
Title   : set_gap
Usage   : $matrix->set_gap('-');
Function: Assigns the gap (indel?) character symbol.
Returns : Modified object.
Args    : A symbol used to indicate gaps. 
          Default is '-'.

set_ntax()

Type    : Mutator
Title   : set_ntax
Usage   : $matrix->set_ntax(10);
Function: Assigns the intended number of 
          taxa for the matrix.
Returns : Modified object.
Args    : Optional: An integer. If no
          value is given, ntax is reset
          to the undefined default.
Comments: This value is only necessary 
          for the $matrix->validate 
          method. If you don't need to
          call that, this value is 
          better left unset.

set_nchar()

Type    : Mutator
Title   : set_nchar
Usage   : $matrix->set_nchar(10);
Function: Assigns the intended number of 
          characters for the matrix.
Returns : Modified object.
Args    : Optional: An integer. If no
          value is given, nchar is reset
          to the undefined default.
Comments: This value is only necessary 
          for the $matrix->validate 
          method. If you don't need to
          call that, this value is 
          better left unset.

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

Type    : Accessor
Title   : get_num_characters
Usage   : my $nchar = $matrix->get_num_characters;
Function: Retrieves number of characters
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_num_taxa()

Type    : Accessor
Title   : get_num_taxa
Usage   : my $ntax = $matrix->get_num_taxa;
Function: Retrieves the number of 
          distinct taxa 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_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.

METHODS

validate()

Type    : Method
Title   : validate
Usage   : $matrix->validate;
Function: Compares computed ntax and nchar with
          asserted. Reacts violently if something
          doesn't match.
Returns : Void.
Args    : None
Comments: 'set_ntax' and 'set_nchar' need to be 
          assigned for this to work.

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: N.B.!: 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.

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,v 1.31 2006/04/12 22:38:23 rvosa Exp $

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

To install Bio::Phylo, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Bio::Phylo

CPAN shell

perl -MCPAN -e shell
install Bio::Phylo

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

CONSTRUCTOR

MUTATORS

ACCESSORS

METHODS

DESTRUCTOR

SEE ALSO

FORUM

BUGS

AUTHOR

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Module Install Instructions