Bio::Phylo::Listable - Parent class for listable/iterator objects.
No direct usage, parent class. Methods documented here are available for all objects that inherit from it.
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.
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
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.
Type : Object method Title : delete Usage : $obj->delete($other_obj); Function: Deletes an object from its container. Returns : A Bio::Phylo::Listable object. Args : A Bio::Phylo::* object. Note : Be careful with this method: deleting a node from a tree like this will result in undefined references in its neighbouring nodes. Its children will have their parent reference become undef (instead of pointing to their grandparent, as collapsing a node would do). The same is true for taxon objects that reference datum objects: if the datum object is deleted from a matrix (say), the taxon will now hold undefined references.
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->get_taxon field, and every taxon object has a list of references to datum objects stored in its $taxon->get_data field.
$datum->get_taxon
$taxon->get_data
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:
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.
Type : Test Title : contains Usage : if ( $obj->contains( $other_obj ) ) { # do something } Function: Tests whether the invocant object contains the argument object Returns : BOOLEAN Args : A Bio::Phylo::* object
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.
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.
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.
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.
Returns the 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.
Returns the current internal index of the invocant.
Type : Generic query Title : current_index Usage : my $last_index = $obj->current_index; Function: Returns the current internal index of the invocant. Returns : An integer Args : none.
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.
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 (or array ref for slices). Args : An index or range. This works the way you dereference any perl array including through slices, i.e. C<$obj-E<gt>get_by_index(0 .. 10)> C<$obj-E<gt>get_by_index(0, -1)> and so on. Comments: Throws if out-of-bounds
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
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$/)
The visit method can be used to iterate over all objects in the Listable object. At every iteration, the CODE reference in the argument is applied to the focal object. The object enters the CODE reference as $_[0]. The objects are visited in the order in which they were inserted in the Listable object.
Type : Visitor predicate Title : visit Usage : $obj->visit( sub{ print $_[0]->get_name, "\n" } ); Function: Implements visitor pattern using code reference. Returns : The invocant, possibly modified. Args : a CODE reference.
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.
Iterate over a set of trees.
Iterate over nodes in a tree.
Iterate over a set of matrices.
Iterate over the datum objects in a matrix.
Iterate over the sequences in an alignment.
Iterate over a set of taxa.
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.
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
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:
bug-bio-phylo@rt.cpan.org
$Id: Listable.pm,v 1.31 2006/04/12 22:38:22 rvosa Exp $
Rutger Vos,
rvosa@sfu.ca
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 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.
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.