The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Bio-Phylo-0.08
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Matrices::Matrix

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.

SEE ALSO

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,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

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.