NAME
Bio::Phylo::Listable - Parent class for listable/iterator objects.
SYNOPSIS
No direct usage, parent 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()
-
Listable object constructor.
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()
-
Pushes an object into its container.
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.
- insert_at_index()
-
Inserts argument object in invocant container at argument index.
Type : Object method Title : insert_at_index Usage : $obj->insert_at_index($other_obj, $i); Function: Inserts $other_obj at index $i in container $obj Returns : A Bio::Phylo::Listable object. Args : A Bio::Phylo::* object.
- delete()
-
Deletes argument from invocant 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.
- clear()
-
Empties container object.
Type : Object method Title : clear Usage : $obj->clear(); Function: Clears the container. Returns : A Bio::Phylo::Listable object. Args : Note. Note :
- 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->get_taxon
field, and every taxon object has a list of references to datum objects stored in its$taxon->get_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.
- contains()
-
Tests whether the invocant object contains the argument object.
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
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 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.
- current_index()
-
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.
- 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()
-
Gets element defined by argument index from invocant container.
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. $obj->get_by_index(0 .. 10)> $obj->get_by_index(0, -1) and so on. Comments: Throws if out-of-bounds
VISITOR METHODS
- get_by_value()
-
Gets elements that meet numerical rule from invocant container.
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()
-
Gets elements that match regular expression from invocant container.
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$/)
- visit()
-
Iterates over objects contained by invocant, executes argument code reference on each.
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.
TESTS
- can_contain()
-
Tests if argument can be inserted in invocant.
Type : Test Title : can_contain Usage : &do_something if $listable->can_contain( $obj ); Function: Tests if $obj can be inserted in $listable Returns : BOOL Args : An $obj to test
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::Taxa
-
Iterate over a set of taxa.
Superclasses
- Bio::Phylo
-
The listable class inherits from Bio::Phylo, so look there for more methods applicable to Bio::Phylo::Listable objects and subclasses.
- Bio::Phylo::Util::XMLWritable
-
This object inherits from Bio::Phylo::Util::XMLWritable, so methods defined there are also applicable here.
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 4204 2007-07-13 05:40:14Z rvosa $
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.