/ 
Bio-Phylo-0.05
River stage two • 9 direct dependents • 18 total dependents
/ Bio::Phylo::Listable

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.