NAME
Bio::Phylo::Listable - Abstract class for listable/iterator objects.
SYNOPSIS
No direct usage, abstract class. Methods documented here are available for
all objects that inherit from it.
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, Alignment objects, Taxa, Forest, Tree objects.
METHODS
CONSTRUCTOR
- new()
-
Type : Constructor Title : new Usage : my $obj = Bio::Phylo::Listable->new; Function: Instantiates a Bio::Phylo::Listable object Returns : A Bio::Phylo::Listable object. Args : none
ARRAY METHODS
- insert()
-
Type : Object method Title : insert Usage : $obj->insert($other_obj); Function: Pushes an object into its container. Returns : A Bio::Phylo::Listable object. Args : A Bio::Phylo::* object.
- cross_reference()
-
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 itstaxon->{DATA}
field.Type : Generic method Title : cross_reference Usage : $obj->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 a reference to an array of objects contained by the listable object.
Type : Generic query Title : get_entities Usage : my @entities = @{ $obj->get_entities }; Function: Retrieves all entities in the invocant. Returns : A reference to a list of Bio::Phylo::* objects. Args : none.
ITERATOR METHODS
- first()
-
Jumps to the first element contained by the listable object.
Type : Iterator Title : first Usage : my $first_obj = $obj->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 : Iterator Title : last Usage : my $last_obj = $obj->last; Function: Retrieves the last entity in the invocant. Returns : A Bio::Phylo::* object Args : none.
- current()
-
Returns the current focal element of the listable object.
Type : Iterator Title : current Usage : my $current_obj = $obj->current; Function: Retrieves the current focal entity in the invocant. Returns : A Bio::Phylo::* object Args : none.
- next()
-
Returns the next focal element of the listable object.
Type : Iterator Title : next Usage : my $next_obj = $obj->next; Function: Retrieves the next focal entity in the invocant. Returns : A Bio::Phylo::* object Args : none.
- previous()
-
Returns the next previous element of the listable object.
Type : Iterator Title : previous Usage : my $previous_obj = $obj->previous; Function: Retrieves the previous focal entity in the invocant. Returns : A Bio::Phylo::* object Args : none.
- last_index()
-
Returns the highest valid index of the invocant.
Type : Generic query Title : last_index Usage : my $last_index = $obj->last_index; Function: Returns the highest valid index of the invocant. Returns : An integer Args : none.
- get_by_index()
-
The get_by_index method is used to retrieve the i'th entity contained by a listable object.
Type : Query Title : get_by_index Usage : my $contained_obj = $obj->get_by_index($i); Function: Retrieves the i'th entity from a listable object. Returns : An entity stored by a listable object. Args : An index; Comments: Throws if out-of-bounds
VISITOR METHODS
- get_by_value()
-
The get_by_value method can be used to filter out objects contained by the listable object that meet a numerical condition.
Type : Visitor predicate Title : get_by_value Usage : my @objects = @{ $obj->get_by_value( -value => $method, -ge => $number ) }; Function: Iterates through all objects contained by $obj and returns those for which the output of $method (e.g. get_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 reference to an array 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()
-
The get_by_regular_expression method can be used to filter out objects contained by the listable object that match a regular expression.
Type : Visitor predicate Title : get_by_regular_expression Usage : my @objects = @{ $obj->get_by_regular_expression( -value => $method, -match => $re ) }; Function: Retrieves the data in the current Bio::Phylo::Listable object whose $method output matches $re Returns : A list of Bio::Phylo::* objects. Args : -value => any of the string datum props (e.g. 'get_type') -match => a compiled regular expression (e.g. qr/^[D|R]NA$/)
SEE ALSO
Objects inheriting from Bio::Phylo::Listable
- Bio::Phylo::Forest
-
Iterate over a set of trees.
- Bio::Phylo::Forest::Tree
-
Iterate over nodes in a tree.
- Bio::Phylo::Matrices
-
Iterate over a set of matrices.
- Bio::Phylo::Matrices::Matrix
-
Iterate over the datum objects in a matrix.
- Bio::Phylo::Matrices::Alignment
-
Iterate over the sequences in an alignment.
- Bio::Phylo::Taxa
-
Iterate over a set of taxa.
Superclass
- Bio::Phylo
-
The listable class inherits from Bio::Phylo, so look there for more methods applicable to Bio::Phylo::Listable objects and subclasses.
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: Listable.pm,v 1.23 2005/09/29 20:31:17 rvosa Exp $
AUTHOR
Rutger 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 Vos, All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.