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 its taxon->{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.

cpanm Bio::Phylo

perl -MCPAN -e shell
install Bio::Phylo