NAME

Bio::Phylo::Listable - A base module for analyzing and manipulating phylogenetic trees.

SYNOPSIS

No direct usage, abstract class.

DESCRIPTION

A listable object is an object that contains multiple smaller objects of the same type. For example: a tree contains nodes, so it's a listable object.

This class contains methods that are useful for all listable objects: Matrices, Matrix objects, Taxa, Trees, Tree objects.

The underlying assumption is, as of now, that listable objects are blessed anonymous arrays.

METHODS

CONSTRUCTOR

new()

Type    : Constructor
Title   : new
Usage   : my $obj = new Bio::Phylo::Listable;
Function: Instantiates a Bio::Phylo::Listable object
Returns : A Bio::Phylo::Listable object.
Args    : none

insert($obj)

Since listable objects are arrays, we can simply add to them (e.g. adding a node to a tree, without regard to how it is connected to others) by using push. To make sure we're pushing the right objects into the array we have to check their type. Since we don't want to test for ref (might break if we subclass) I created these container and container_type methods, that simply return a string saying what object is its container (e.g. for a node a TREE is its container), and what type of container the invocant object is (so for a node the NODE string is returned).

Type    : Object method
Title   : insert(Bio::Phylo::*)
Usage   : $invocant->insert($obj);
Function: Adds an object to the invocant.
Returns : A Bio::Phylo::Listable object.
Args    : A Bio::Phylo::* object.

cross_reference(Bio::Phylo::Taxa)

The cross_reference method links node and datum objects to the taxa they apply to. After crossreferencing a matrix with a taxa object every datum object has a reference to a taxon object stored in its datum->[TAXON] field, and every taxon object has a list of references to datum objects stored in its taxon->[DATA] field.

Type    : Generic method
Title   : cross_reference(Bio::Phylo::Taxa)
Usage   : $invocant->cross_reference($taxa);
Function: Crossreferences the entities in the invocant with names in $taxa
Returns : string
Args    : A Bio::Phylo::Taxa object
Comments:

get_entities()

Returns the full array of objects contained by the listable object.

Type    : Generic query
Title   : get_data
Usage   : $invocant->get_entities;
Function: Retrieves all entities in the invocant.
Returns : A list of Bio::Phylo::* objects.
Args    : none.

first()

Jumps to the first element contained by the listable object.

Type    : Generic query
Title   : first
Usage   : $invocant->first;
Function: Retrieves the first entity in the invocant.
Returns : A Bio::Phylo::* object
Args    : none.

last()

Jumps to the last element contained by the listable object.

Type    : Generic query
Title   : last
Usage   : $invocant->last;
Function: Retrieves the last entity in the invocant.
Returns : A Bio::Phylo::* object
Args    : none.

last_index()

Jumps to the last element contained by the listable object.

Type    : Generic query
Title   : last_index
Usage   : $invocant->last_index;
Function: Returns the highest valid index of the invocant.
Returns : An integer
Args    : none.

get_by_value(%options)

The get_by_value method can be used to filter out objects contained by the listable object that meet a numerical condition.

Type    : Generic method
Title   : get_by_value(%options)
Usage   : $invocant->get_by_value(-value => $value, -ge => $number );
Function: Iterates through all objects returned by invocant and returns those
          for which their $value (e.g. tree length) is less than (-lt),
          less than or equal to (-le), equal to (-eq), greater than or equal to
          (-ge), or greater than (-gt) $number.
Returns : A list of objects
Args    : -value = any of the numerical obj data (e.g. tree length)
          -lt = less than
          -le = less than or equals
          -eq = equals
          -ge = greater than or equals
          -gt = greater than

get_by_regular_expression(%options)

The get_by_regular_expression method can be used to filter out objects contained by the listable object that match a regular expression.

Type    : Query
Title   : get_by_regular_expression(-value => $varname, -match => $re)
Usage   : $matrix->get_by_regular_expression(
               -value => type,
               -match => ^[D|R]NA$
           );
Function: Retrieves the data in the current
          Bio::Phylo::Listable object whose $varname matches $re
Returns : A list of Bio::Phylo::* objects.
Args    : -value = any of the string datum props (e.g. 'type', 'char')
          -match = a regular expression without delimiters.
Comments: In the usage example all datum objects whose type is either DNA
          or RNA are returned.

get_by_index($i)

The get_by_index method is used to retrieve the i'th entity contained by a listable object.

Type    : Query
Title   : get_by_index($i)
Usage   : $matrix->get_by_index($i);
Function: Retrieves the i'the entity from a listable object.
Returns : An entity stored by a listable object.
Args    : An index;
Comments: Throws if out-of-bounds

AUTHOR

Rutger Vos, <rvosa@sfu.ca> http://www.sfu.ca/~rvosa/

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.

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 Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.